Passer au contenu principal
Cette page décrit les champs à renseigner lorsque vous enregistrez un webhook dans le dashboard (Settings > Webhooks > Add webhook +).

URL de l’endpoint

L’URL qui reçoit les notifications. Il doit s’agir d’une URL https publique avec un certificat TLS valide, non auto-signé. Bodyguard refuse les webhooks enregistrés avec une URL http.

Événements

Un webhook est déclenché par un ou plusieurs événements auxquels vous vous abonnez : Un même webhook peut s’abonner à plusieurs événements. Vous pouvez aussi ajouter un autre webhook avec une URL différente pour traiter d’autres événements séparément.
Bodyguard envoie aussi un événement webhook.validate, auquel vous ne pouvez pas vous abonner. Votre endpoint doit y répondre avec un code de statut 2xx lorsque vous activez le webhook, et lorsque vous modifiez l’URL ou les en-têtes personnalisés d’un webhook activé.
Pour le contenu de chaque événement, consultez Payloads.

Secret de signature

Bodyguard génère un secret de signature pour chaque webhook. Il commence par whsec_, suivi d’une valeur encodée en base64. Le dashboard ne l’affiche qu’une seule fois, à la création du webhook : copiez-le à ce moment-là. Consultez Connecter votre webhook. Bodyguard l’utilise pour signer chaque requête, et vous l’utilisez pour vérifier qu’une requête provient de Bodyguard et n’a pas été altérée. Voir Démarrage rapide.
Traitez le secret de signature comme un mot de passe. Conservez-le dans un gestionnaire de secrets ou une variable d’environnement, et ne l’exposez jamais dans du code côté client.

En-têtes personnalisés

Les en-têtes personnalisés sont des en-têtes HTTP facultatifs que vous ajoutez à un webhook sous forme de paires clé/valeur. Bodyguard les inclut dans chaque requête qu’il envoie à votre endpoint, y compris les événements webhook.validate. Par exemple, utilisez-les pour envoyer un jeton attendu par votre passerelle d’API. Les en-têtes personnalisés respectent les règles suivantes :
  • Un webhook peut avoir jusqu’à 20 en-têtes personnalisés.
  • Chaque clé et chaque valeur est limitée à 256 caractères.
  • Une clé doit être un nom d’en-tête HTTP valide.
  • Les clés ne sont pas sensibles à la casse : vous ne pouvez pas définir deux fois la même clé, même avec une casse différente.
  • Les en-têtes standard, définis par Bodyguard ou par le protocole HTTP, ne peuvent pas être utilisés comme en-têtes personnalisés, quelle que soit leur casse : par exemple Content-Type, webhook-signature ou User-Agent.
Si vous modifiez les en-têtes personnalisés d’un webhook activé, Bodyguard envoie un événement webhook.validate avec les nouveaux en-têtes. Si votre endpoint ne répond pas avec un code de statut 2xx, la modification échoue et le webhook conserve ses en-têtes précédents.
Les en-têtes personnalisés ne remplacent pas la vérification de la signature. Vérifiez toujours l’en-tête webhook-signature de chaque requête, comme décrit dans le Démarrage rapide.

Contacts

Chaque nouveau webhook nécessite au moins un contact. Bodyguard envoie des alertes à chaque contact s’il rencontre des problèmes pour joindre votre endpoint, comme les e-mails décrits dans Gérer les erreurs. Chaque contact doit être un utilisateur enregistré dans votre organisation sur le dashboard.

Statuts du webhook

Chaque webhook a un statut qui décrit son état actuel : Le statut ERROR est défini automatiquement. Tant qu’un webhook est DISABLED ou ERROR, Bodyguard n’envoie pas ses événements, et ils ne peuvent pas être renvoyés lorsque vous réactivez le webhook. Pour réactiver un webhook en erreur, corrigez le problème, puis activez-le manuellement depuis le dashboard. Voir Gérer les erreurs.

Étapes suivantes

Payloads

En-têtes, structure du payload et un exemple pour chaque type d’événement.