Passer au contenu principal
Bodyguard signe chaque requête webhook, afin que vous puissiez vérifier qu’elle provient de Bodyguard et que personne ne l’a altérée. Les signatures suivent la spécification Standard Webhooks : vous les vérifiez avec les bibliothèques open source officielles, sans écrire vous-même la cryptographie.

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 :
Créez ensuite un endpoint qui accepte les requêtes 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.
Vérifiez le corps brut de la requête, exactement tel que reçu. Si un framework analyse le JSON et que vous le sérialisez à nouveau, les espaces et l’ordre des clés peuvent changer et la vérification de la signature échoue.
L’événement 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.
Si aucune bibliothèque ne convient à votre stack, implémentez la vérification décrite dans la spécification Standard Webhooks :
  1. Lisez les en-têtes webhook-id, webhook-timestamp et webhook-signature.
  2. Rejetez la requête si webhook-timestamp est trop éloigné de l’heure actuelle (les bibliothèques officielles utilisent cinq minutes).
  3. Construisez le contenu signé : {webhook-id}.{webhook-timestamp}.{corps brut}.
  4. 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.
  5. Comparez-le, en temps constant, à chaque signature v1, de l’en-tête webhook-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énement webhook.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 2xx sous 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ête webhook-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.