Qu'est-ce qu'un Webhook et comment l'intégrer ?

La réponse la plus courte à la question « qu'est-ce qu'un webhook » est la suivante : lorsqu'un événement se produit dans un système, ce système envoie automatiquement une requête HTTP vers une URL que vous définissez. Ainsi, au lieu de demander sans cesse « quelque chose de nouveau s'est-il passé ? », l'autre partie vous appelle au moment où l'événement survient. Cette petite inversion constitue l'épine dorsale des intégrations modernes : prestataires de paiement, plateformes Git, Discord, services d'e-mail et presque tous les produits SaaS reposent sur les webhooks.

La différence entre polling et webhook

Dans le modèle de polling (sondage), votre application interroge régulièrement l'API distante en demandant « quelque chose a-t-il changé ? ». La plupart du temps la réponse est « non », donc l'essentiel de vos requêtes est gaspillé. Même en demandant une fois par minute, vous obtenez un délai moyen de 30 secondes entre l'événement et sa découverte.

Avec le modèle webhook, vous travaillez de façon événementielle : dès qu'une chose change, l'autre partie pousse instantanément les données vers votre endpoint. Les avantages sont clairs :

• Temps réel : vous êtes prévenu à l'instant où l'événement se produit, la latence se compte en millisecondes, pas en secondes.
• Efficacité : au lieu de milliers de requêtes inutiles, le trafic n'est généré que pour de vrais événements.
• Scalabilité : votre serveur n'est pas épuisé par des requêtes superflues et vous ne heurtez pas les limites de débit.

Le polling garde sa place : lorsque l'autre partie n'offre pas de webhooks, ou lorsqu'une livraison garantie est une exigence stricte. Mais si vous avez le choix, l'approche événementielle est presque toujours plus propre.

À quoi ressemble une requête webhook ?

Une requête webhook n'est en réalité qu'un simple POST HTTP. Le système émetteur transporte les détails de l'événement, généralement dans un corps JSON. Une confirmation de paiement, par exemple, pourrait ressembler à ceci :

POST /webhooks/payment HTTP/1.1
Host: votre-site.com
Content-Type: application/json
X-Signature: t=1719500000,v1=4a9f...c2

{
  "event": "payment.succeeded",
  "data": {
    "id": "pay_8sK2",
    "amount": 4900,
    "currency": "EUR",
    "customer": "cus_12"
  }
}

Votre côté reçoit cette requête, lit le corps, effectue un travail selon le type d'event (confirme la commande, envoie un e-mail, attribue un rôle à l'utilisateur) et renvoie rapidement 200 OK à l'émetteur. Le point critique ici : répondez vite. Déléguez les traitements lourds (générer des rapports, appeler des API externes) à une file d'attente ; ne laissez pas le webhook en attente.

Construire un récepteur de webhook avec Laravel

En pratique, écrire un endpoint de webhook est très simple. Avec Laravel, une route et un contrôleur suffisent :

// routes/web.php
Route::post('/webhooks/payment', [WebhookController::class, 'handle'])
    ->withoutMiddleware([VerifyCsrfToken::class]);

Attention : les webhooks proviennent de systèmes externes et ne transportent aucun cookie de session ; il faut donc exclure la protection CSRF de cette route. Côté contrôleur, nous traitons l'événement :

public function handle(Request $request)
{
    $payload = $request->all();

    if ($payload['event'] === 'payment.succeeded') {
        ProcessPayment::dispatch($payload['data']);
    }

    return response()->json(['ok' => true]);
}

Ici, nous confions le travail à un job de file d'attente avec ProcessPayment::dispatch(...) ; ainsi le contrôleur répond instantanément et le travail lourd s'exécute en arrière-plan.

Vérification de signature : le cœur de la sécurité des webhooks

Comme votre URL de webhook est accessible publiquement, vous devez empêcher un acteur malveillant d'envoyer de fausses requêtes. La plupart des prestataires signent le corps avec un secret partagé via HMAC et envoient la signature dans un en-tête (par ex. X-Signature). Vous recalculez la signature avec la même clé et comparez :

$signature = $request->header('X-Signature');
$expected  = hash_hmac('sha256', $request->getContent(), $secret);

if (! hash_equals($expected, $signature)) {
    abort(403, 'Signature invalide');
}

Détail crucial : calculez la signature sur le corps brut (getContent()), pas sur le tableau parsé, car re-sérialiser le JSON peut introduire des différences au niveau des octets. Utilisez aussi hash_equals(), car == est vulnérable aux attaques temporelles.

Fiabilité : nouvelles tentatives et idempotence

Dans le monde réel, tout ne se passe pas toujours bien. Si votre serveur ne peut répondre un instant, la plupart des prestataires réessaient la requête. Cela signifie que le même événement peut arriver plusieurs fois. Vos gestionnaires doivent donc être idempotents :

• Chaque événement possède un champ id unique ; stockez-le.
• Si le même id revient, ne refaites pas le travail — renvoyez simplement 200.
• Renvoyez un 2xx rapide ; une réponse lente fait que le prestataire vous considère en échec et réessaie inutilement.

Pour tester les webhooks pendant le développement, vous pouvez exposer votre serveur local avec un outil de tunnel comme ngrok et déclencher des événements de test depuis le tableau de bord du prestataire.

Questions fréquentes

Quelle est la différence entre un webhook et une API ?

Une API est généralement un modèle « pull » où vous initiez la requête : vous demandez, vous obtenez une réponse. Un webhook est un modèle « push » : lorsqu'un événement se produit, l'autre partie vous envoie les données. La plupart des intégrations utilisent les deux ensemble.

Comment sécuriser mon URL de webhook ?

Utilisez toujours HTTPS, vérifiez la signature de chaque requête entrante, ajoutez si possible la plage d'IP du prestataire à une liste d'autorisation, et conservez le secret dans une variable d'environnement (.env) plutôt que dans le code.

Que faire si un webhook n'arrive pas ?

Consultez d'abord les journaux de livraison du prestataire ; la plupart affichent les tentatives échouées et le code HTTP renvoyé. Assurez-vous que votre endpoint renvoie bien 200 en journalisant le corps brut, et au besoin renvoyez l'événement manuellement depuis le tableau de bord.

Besoin d'une intégration événementielle ? Je peux vous aider à construire des flux de webhooks sécurisés pour les paiements, Discord, Git ou vos propres systèmes. Contactez-moi et parlons de votre projet.