Prérequis
- Le secret de signature de votre webhook. Il commence par
whsec_. Voir Configuration. - Un serveur capable d’exposer un endpoint HTTPS public.
- L’endpoint doit établir une négociation TLS valide, avec un certificat émis par une autorité de certification reconnue. Les certificats auto-signés ne sont pas acceptés.
- L’endpoint doit répondre sous 10 secondes. Sinon, la livraison est considérée comme un échec.
Fonctionnement de la signature
Bodyguard signe chaque requête comme décrit dans la section Verifying webhook authenticity de la spécification Standard Webhooks. Bodyguard utilise le schéma de signature symétrique :HMAC-SHA256 avec votre secret de signature whsec_, et l’identifiant de signature v1.
Créer votre endpoint
Installez la bibliothèque correspondant à votre langage :POST et vérifie chacune d’elles. Transmettez le secret de signature dans la variable d’environnement BODYGUARD_WEBHOOK_SECRET. Pour le contenu de event.data, consultez Payloads › Types d’événements.
webhook.validate ne nécessite aucun traitement particulier : il est signé comme n’importe quel autre événement, votre endpoint le vérifie donc et répond avec un code de statut 2xx.
Lancez votre endpoint :
Autres langages
Standard Webhooks fournit aussi des bibliothèques pour Java et Kotlin, Rust, Ruby, PHP, C# et Elixir. Consultez la liste des bibliothèques.Vérifier une signature sans bibliothèque
Vérifier une signature sans bibliothèque
Si aucune bibliothèque ne convient à votre stack, implémentez la vérification décrite dans la spécification Standard Webhooks :
- Lisez les en-têtes
webhook-id,webhook-timestampetwebhook-signature. - Rejetez la requête si
webhook-timestampest trop éloigné de l’heure actuelle (les bibliothèques officielles utilisent cinq minutes). - Construisez le contenu signé :
{webhook-id}.{webhook-timestamp}.{corps brut}. - Retirez le préfixe
whsec_de votre secret de signature et décodez le reste en base64. Calculez le HMAC SHA256 du contenu signé avec cette clé, puis encodez le résultat en base64. - Comparez-le, en temps constant, à chaque signature
v1,de l’en-têtewebhook-signature. La requête est valide si l’une d’elles correspond.
Tester votre endpoint
Lorsque vous enregistrez le webhook ou modifiez son URL, Bodyguard envoie un événementwebhook.validate : si votre endpoint ne répond pas avec un code de statut 2xx, l’enregistrement échoue. Pour vérifier votre endpoint à tout moment, cliquez sur Send test event dans le dashboard.
Traiter les événements en toute sécurité
- Répondez rapidement. Renvoyez un code de statut
2xxsous 10 secondes, dès que vous avez vérifié et stocké l’événement, et effectuez le traitement lourd ensuite. Toute autre réponse, ou l’absence de réponse, est un échec et déclenche une nouvelle tentative. - Dédoublonnez avec
webhook-id. Bodyguard retente les livraisons échouées avec le même en-têtewebhook-id. Stockez les identifiants que vous avez déjà traités, et ignorez ceux que vous avez déjà vus. - Gardez le secret privé. Chargez-le depuis l’environnement et ne l’écrivez jamais dans les logs.
Étapes suivantes
Configuration
Événements, secret de signature, contacts et statuts du webhook.