Qu'est-ce qu'un webhook ?

Lorsque Bird appelle votre endpoint, le récepteur doit conserver l'événement avant de commencer tout traitement. Un webhook est une requête HTTP qu'un système envoie à votre application lorsqu'un événement se produit. L'expéditeur signe le POST vers votre URL enregistrée. Votre récepteur décide quand l'événement est durablement accepté.

En quoi un webhook diffère-t-il de l'interrogation périodique d'une API ?

L'interrogation périodique signifie que votre application appelle une API à intervalles réguliers et vérifie les changements. Un webhook inverse cette direction : le fournisseur appelle votre endpoint lorsqu'un événement se produit, ce qui vous évite les requêtes inutiles et vous permet de réagir plus vite.

Les webhooks nécessitent un endpoint HTTPS public capable de recevoir des requêtes pendant la livraison des événements. L'interrogation périodique fonctionne depuis n'importe où et laisse votre application choisir quand récupérer l'état. Utilisez les webhooks pour des notifications en temps utile. Utilisez l'API pour récupérer plus de détails sur une ressource lorsqu'un événement ne contient que des identifiants.

À quoi ressemble une requête webhook ?

Une requête webhook est un HTTP POST avec des en-têtes et une enveloppe d'événement JSON. L'événement de livraison d'e-mail de Bird contient type, un timestamp d'événement, et des data spécifiques au type :

{
  "type": "email.delivered",
  "timestamp": "2026-06-10T14:30:00Z",
  "data": {
    "email_id": "em_01krdgeqcxet5s7t44vh8rt9mg",
    "recipient_id": "er_01krdgeqcxet5s7t44vh8rt9mg",
    "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
    "recipient": "user@example.com",
    "recipient_role": "to",
    "tags": [{ "name": "category", "value": "welcome" }],
    "metadata": { "order_id": "ord_123" },
    "broadcast_id": null
  }
}

L'identifiant du message est data.email_id. L'identité de livraison est l'en-tête webhook-id, qui reste identique lorsque Bird réessaye ou rejoue cet événement. Le champ timestamp du corps enregistre le moment où l'événement s'est produit. L'en-tête webhook-timestamp enregistre cette tentative de livraison, les deux horodatages répondent donc à des questions différentes. Consultez les champs d'événement e-mail pour les charges utiles spécifiques à chaque événement.

Comment vérifier la signature d'un webhook ?

Conservez les octets bruts de la requête et vérifiez la signature avant d'analyser ou de stocker l'événement. Le SDK de Bird vérifie les en-têtes webhook-id, webhook-timestamp et webhook-signature. Il applique la tolérance d'horodatage pour vous. Utilisez le guide de signature au lieu d'écrire un second vérificateur.

Si vous avez besoin de comprendre l'entrée de signature, Bird utilise {webhook-id}.{webhook-timestamp}.{raw request body}. Le secret de l'endpoint commence par whsec_ ; supprimez ce préfixe et décodez le reste en base64 avant de calculer HMAC-SHA256. Pendant la rotation du secret, l'en-tête de signature peut contenir plusieurs valeurs v1, séparées par des espaces : acceptez une valeur correspondante parmi les secrets actifs.

Rejetez les requêtes malformées, non authentifiées ou périmées avant le stockage. Analyser JSON en premier peut modifier les espaces ou l'ordre des clés, et les octets ne correspondent alors plus au message signé.

Comment stocker et acquitter un webhook ?

Persistez un événement vérifié et son travail durable avant de renvoyer un succès. Insérez l'événement indexé par webhook-id. Insérez l'élément de travail pour un nouvel événement. Validez les deux dans une seule transaction ou un schéma équivalent d'inbox et outbox durables.

read raw bytes and headers
verify the signature and timestamp with the Bird SDK
begin a durable transaction
  insert the inbox event keyed by webhook-id, unless it already exists
  insert a durable work item for a new event
commit the transaction
return 204
worker processes the persisted event idempotently

Un doublon déjà stocké durablement peut recevoir 204 sans créer de travail supplémentaire. Renvoyez un statut non 2xx lorsque la validation durable échoue, afin que Bird réessaye la livraison. Une fois le succès renvoyé, relancez le worker local depuis votre enregistrement durable au lieu d'attendre que Bird renvoie l'événement.

Cet ordonnancement est un modèle applicatif pour la sémantique de livraison au-moins-une-fois de Bird. Ce n'est pas une file d'attente que Bird gère pour vous. Le guide de déduplication et d'idempotence couvre la décision de déduplication plus en détail.

Comment fonctionnent les réessais et le rejeu de webhooks ?

Bird accorde 15 secondes à une livraison normale pour recevoir une réponse. Tout statut 2xx est un succès. Un statut non 2xx, une redirection ou un délai d'attente dépassé échoue et suit le calendrier de réessai.

La courbe comporte 8 tentatives, requête initiale comprise. Chaque délai s'applique avec un jitter de plus ou moins 20 %. Un 429 ou un délai de connexion dépassé porte le délai de base à 60 secondes. Une valeur Retry-After positive est bornée entre ce délai de base et le double du délai de base avant jitter, le tableau décrit donc des délais de base et non des heures d'arrivée exactes. Consultez comment les webhooks échoués sont réessayés pour le parcours d'échec.

Les livraisons ne sont pas ordonnées : ne mettez pas à jour l'état applicatif courant en vous fiant uniquement à l'ordre d'arrivée. Utilisez le timestamp de l'événement et l'état de votre ressource lorsque les événements peuvent arriver dans le désordre.

Lorsqu'une livraison est manquée, inspectez les tentatives de webhook. Corrigez le récepteur. Créez un rejeu de webhook. Bird ignore les livraisons que l'endpoint a déjà reçues avec succès. Un rejeu réutilise le webhook-id d'origine, la même clé de déduplication le protège donc.

Que connecter après avoir appris les bases des webhooks ?

Créez un endpoint. Vérifiez et acceptez durablement ses livraisons signées. Inspectez les tentatives de livraison. Rejouez les événements manqués. Puis utilisez la rotation du secret pour déployer un nouveau secret de signature sans perdre de livraisons.