Échecs webhook
Symptôme A : Le point de terminaison webhook renvoie 4xx/5xx
Comment vérifier : Tableau de bord → Propriété → Webhooks → Journal de livraison — affiche les codes de statut et corps de réponse.
Causes et corrections :
| Code de statut | Cause probable | Correction |
|---|---|---|
401 | Échec de vérification de signature | Vérifiez votre code de vérification — voir Sécurité des webhooks |
400 | Votre point de terminaison rejette le format du payload | Enregistrez le corps brut et vérifiez par rapport au schéma de payload |
404 | L'URL du point de terminaison a changé | Mettez à jour l'URL du webhook dans Propriété → Webhooks → [Webhook] → Modifier |
500 | Bug dans votre gestionnaire de webhook | Vérifiez vos journaux serveur pour l'erreur |
timeout | Votre point de terminaison met trop de temps à répondre | Répondez avec 200 immédiatement, traitez de manière asynchrone |
Symptôme B : Échec de vérification de signature webhook
Cause : Raisons les plus courantes :
- Chaîne de signature construite incorrectement — doit être
{timestamp}.{raw_body}(pas le JSON parsé) - Utilisation d'un secret différent de celui affiché dans le tableau de bord
- Lecture d'un corps mis en tampon/modifié au lieu des octets bruts
Correction : Assurez-vous de lire le corps de requête brut avant tout parsing JSON. Dans Express :
// DOIT utiliser le middleware de corps brut
app.use('/webhooks', express.raw({ type: '*/*' }));
Symptôme C : Les livraisons webhook sont retardées
Cause : ConsentForge réessaie les livraisons échouées avec un backoff exponentiel — les retards sont attendus après des échecs initiaux.
Correction : Corrigez l'erreur sous-jacente (voir Symptôme A). Une fois que votre point de terminaison renvoie 2xx, les livraisons futures seront immédiates.
Symptôme D : Livraisons manquantes — événements non reçus
Comment vérifier : Comparez le nombre de livraisons dans le journal du tableau de bord avec le nombre reçu par votre serveur.
Cause : Certains événements peuvent avoir épuisé toutes les tentatives de réessai (5 tentatives sur ~2 heures).
Correction : Propriété → Webhooks → Journal de livraison → Filtrer : Échoués — utilisez le bouton Rejouer pour renvoyer les livraisons échouées.