Incompatibilité de signature
La cause la plus courante est la signature du JSON analysé au lieu du corps brut exact, ou l'utilisation d'un horodatage différent de celui de l'en-tête de la requête.
Testeur Webhook
Testez vos WebhooksVérifiez la signature
Modifiez un exemple de corps, générez une signature HMAC-SHA256 et une requête cURL pour votre environnement de test.
01
Configurez le test
Saisissez l’URL, le secret de test et l’horodatage.
La signature est calculée dans le navigateur. Utilisez un secret de test.
Horodatage Unix en millisecondes, comme dans les en-têtes BoltUtil.
02
Modifiez le corps, générez la signature
La signature et cURL suivent vos modifications du JSON.
Signature
HMAC-SHA256Saisissez un secret, un horodatage et un JSON valides.
Calculée à partir de l’horodatage, du corps exact et du secret de test.
JSON valide
cURL / POSTRequête de test
Saisissez une URL, un secret, un horodatage et un JSON valides.Exemple de callback de commande USDC, adaptable à USDT. Commande, adresses et hash sont fictifs et ne prouvent aucun paiement.
Cet outil n’envoie aucune requête. Exécutez cURL dans votre environnement de test.
Vérification
Vérifiez avant de poursuivre
Vérifiez avec la même règle, enregistrez l’événement puis mettez à jour la commande.
Guide de vérificationHMAC_SHA256(timestamp + "." + rawBody, secret)- 01
Vérifier le corps brut
Utilisez l'horodatage en millisecondes de l'en-tête et le corps brut exact pour calculer HMAC avant d'analyser JSON. Les espaces, les sauts de ligne et l'ordre des champs affectent la signature.
- 02
Utiliser une comparaison sécurisée
Comparez la signature reçue avec un assistant à temps constant fourni par votre environnement d'exécution de langage.
- 03
Enregistrez en toute sécurité, puis renvoyez 2xx
Renvoyez le succès uniquement après avoir enregistré l'événement ou l'avoir placé dans une file d'attente interne durable.
Dépannage du Webhook
Ne correspond pas ? Commencez ici
Vérifiez le corps d'origine, le secret et l'état de la réponse pour localiser le problème.
Mauvais secret
Utilisez le secret du webhook configuré pour le point de terminaison du commerçant. Les clés API et les secrets de webhook doivent être traités comme des informations d'identification différentes.
L'analyseur de corps a modifié la charge utile
Le middleware JSON peut réorganiser ou reformater les charges utiles. Capturez le corps brut avant l'analyse lors de la vérification des signatures HMAC.
Le point de terminaison renvoie un type non-2xx
Une réponse hors 2xx indique un échec. Les nouvelles tentatives dépendent du type de callback, du statut HTTP et de la politique.
Le traitement n’est pas idempotent
Dédupliquez par commande et statut, ou ID d’événement unique. Un hash peut contenir plusieurs transferts.
Le succès avant la durabilité
Renvoyez HTTP 2xx uniquement après avoir écrit l'événement dans votre base de données ou votre file d'attente. Sinon, un crash peut entraîner la perte d'une notification de paiement complétée.
FAQ
Questions lors du débogage
Vérification des signatures, réponses et livraisons en double.
Pourquoi la vérification de ma signature webhook échoue-t-elle ?
Vérifiez le corps exact de la requête brute, l’en-tête d’horodatage et le secret du webhook configuré. La signature d'un JSON analysé ou d'un corps reformaté produit généralement un HMAC différent.
Mon point de terminaison de webhook doit-il renvoyer SUCCESS dans le corps de la réponse ?
Non. BoltUtil utilise le statut HTTP : 2xx indique la réception. Vérifiez et enregistrez l’événement avant de répondre.
Comment dois-je gérer les diffusions de webhooks en double ?
Utilisez une contrainte unique ou une opération atomique par commande et statut, ou ID d’événement. Le hash seul ne suffit pas.
Quand mon point de terminaison doit-il renvoyer HTTP 2xx ?
Répondez 2xx après vérification et enregistrement. En cas d’échec, utilisez un statut adapté ; les tentatives dépendent du callback et de la politique.