Faire tourner les webhooks en production

La section webhooks couvre les bases ; voici la checklist de production.

Le contrat

• La livraison est au moins une fois et non ordonnée. Dédoublonnez par id d'événement et traitez data.object comme l'état actuel à jour, pas comme un diff.
• Répondez 2xx rapidement (mettez en file d'attente, puis traitez). Le délai d'expiration est de 10 s.
• Nouvelles tentatives : 1 min → 5 min → 30 min → 2 h → 12 h, puis la livraison est en échec.
• Après 20 échecs consécutifs, l'endpoint est désactivé automatiquement. Vous le verrez dans Paramètres → Développeurs → Webhooks (réactivez-le après correction).

Vérifier chaque livraison

Vérifiez X-Nembol-Signature (t=…,v1=…, HMAC-SHA256 de <t>.<raw body> avec le secret de votre endpoint). Le code complet se trouve dans Vérifier les signatures. Pendant une rotation du secret, l'ancienne et la nouvelle signature sont envoyées pendant 24 h.

Pièges à éviter

• Utilisez le corps brut de la requête pour le HMAC. Toute re-sérialisation casse la signature.
• Vous avez manqué une période ? Les livraisons en échec peuvent être renvoyées depuis le tableau de bord (Webhooks → livraisons → Renvoyer), et GET /events vous sert de rattrapage : les événements sont conservés 30 jours.
• Les endpoints doivent être en HTTPS sur un hôte public : un nom de domaine (pas d'adresse IP, pas de localhost, *.localhost, *.local ni *.internal) qui résout vers une adresse publique. Un nom qui résout vers une adresse privée ou interne est refusé au moment de la livraison (la tentative échoue).
• Testez d'abord : l'option Envoyer un événement de test du tableau de bord envoie à votre endpoint un événement fictif signé. Mettez en place la vérification de signature avant de passer en production.

Dernière mise à jour le 20 octobre 2026