URL de l’endpoint
L’URL qui reçoit les notifications. Il doit s’agir d’une URLhttps 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é.Secret de signature
Bodyguard génère un secret de signature pour chaque webhook. Il commence parwhsec_, 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.
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énementswebhook.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-signatureouUser-Agent.
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.