Webhooks
Des envois d'événements signés vers votre endpoint, avec nouvelles tentatives et un journal des envois.
Un webhook envoie un POST HTTP à votre endpoint chaque fois qu’il se passe quelque chose : un e-mail est distribué, un contact se désinscrit, un message arrive. Ajoutez des endpoints dans le tableau de bord sous Webhooks, ou avec POST /webhooks, et choisissez les événements que chacun reçoit. Les SDK vérifient les envois avec verifyWebhook (Node.js) et verify_webhook (Python).
curl -X POST "https://api.billionsend.com/webhooks" \
-H "Authorization: Bearer bs_..." \
-H "Content-Type: application/json" \
-d '{
"endpoint": "https://example.com/webhooks/email",
"events": ["email.delivered", "email.bounced"]
}'
La réponse contient le signing_secret (whsec_...). GET /webhooks/{id} le renvoie de nouveau, et les lignes d’une liste ne l’incluent jamais.
Événements
Événements d’e-mail
| Événement | Déclenché quand |
|---|---|
email.scheduled |
Un e-mail a été accepté avec un scheduled_at dans le futur. |
email.sent |
L’e-mail a été remis au service de messagerie. |
email.delivered |
Le serveur du destinataire l’a accepté. |
email.delivery_delayed |
La distribution est retentée (boîte pleine, greylisting). |
email.bounced |
L’e-mail a rebondi. data.bounce.type vaut Permanent (un rebond permanent : l’adresse est aussi supprimée), Transient ou Undetermined (pas de suppression). |
email.complained |
Le destinataire l’a signalé comme spam. L’adresse est aussi supprimée. |
email.failed |
L’e-mail ne sera jamais envoyé. data.failed.reason en donne la raison. |
email.suppressed |
L’e-mail a été arrêté avant l’envoi. data.suppressed.reason en donne la raison. |
email.opened |
Une personne l’a ouvert (demande le suivi des ouvertures sur le domaine). |
email.clicked |
Une personne a cliqué sur un lien suivi (demande le suivi des clics). |
email.prefetched |
Une machine, et non une personne, a chargé le pixel de suivi ou suivi un lien (proxys de confidentialité, analyseurs de sécurité). Sur abonnement explicite, voir ci-dessous. |
email.received |
Un message est arrivé sur l’un de vos domaines de réception. data.email_id se lit avec GET /emails/receiving/{id}. |
email.prefetched est sur abonnement explicite, comme tous les événements inbox.* : un endpoint ne le reçoit que s’il nomme l’événement, jamais via « tous les événements ».
Événements de compte
Ils ne portent aucun e-mail. data décrit la situation de votre équipe.
| Événement | Déclenché quand |
|---|---|
deliverability.warning |
Votre taux de rebond permanent ou de plainte a franchi le seuil d’avertissement. |
deliverability.paused |
Le taux a franchi le seuil de pause, et les nouveaux envois sont refusés jusqu’à son rétablissement. |
quota.warning |
80 % de votre quota est utilisé (la limite du jour sur Free, le volume inclus de la période de facturation sur les forfaits payants). |
quota.reached |
Le quota est épuisé. |
quota.paused |
Free uniquement : les envois sont retenus jusqu’à minuit UTC ou jusqu’à ce que vous changiez de forfait. |
Événements d’audience
Ils se déclenchent chaque fois qu’un contact ou la liste de suppression change, quel que soit l’auteur de la modification. data contient le contact (id, email, first_name, last_name, unsubscribed, created_at, updated_at) et un source : api, dashboard, hosted_page ou one_click.
| Événement | Déclenché quand | data supplémentaire |
|---|---|---|
contact.created |
Un contact a été ajouté. | |
contact.updated |
Le nom, les propriétés ou l’indicateur de désinscription ont changé. | |
contact.deleted |
Un contact a été supprimé. Après un effacement, l’email vaut [erased], donc fiez-vous à id. |
|
contact.unsubscribed |
Un destinataire a utilisé un lien de désinscription, ou vous avez mis unsubscribed à true. |
domain_id, domain_name (tous deux null pour une désinscription de toute l’équipe) |
contact.resubscribed |
Une désinscription a été annulée. | domain_id, domain_name |
contact.topic_opt_in, contact.topic_opt_out |
L’abonnement d’un contact à une thématique a changé. | topic_id, topic_name |
suppression.added, suppression.removed |
Une adresse est entrée dans la liste de suppression ou en est sortie. | id, email, origin, source, source_id, created_at |
Voir Désinscriptions pour le sens de domain_id.
Événements de boîte de réception
Les boîtes de réception envoient inbox.created, inbox.updated, inbox.deleted, inbox.expired, inbox.thread.created, inbox.thread.folder.updated, inbox.thread.labels.updated, inbox.email.received, inbox.email.sent, inbox.email.quarantined, inbox.draft.created, inbox.draft.updated, inbox.draft.sent, inbox.draft.deleted et inbox.draft.send_failed (un envoi programmé a été refusé ; propre à BillionSend, avec le brouillon et error: { name, message }). Tous sont sur abonnement explicite.
data contient toujours source (api, dashboard ou system) et inbox_id. Les objets e-mail et brouillon ne portent jamais le corps du message : récupérez-le avec l’API.
Pour limiter un endpoint à certaines boîtes de réception, envoyez inbox_ids (jusqu’à 100 boîtes de votre équipe ; null signifie toutes les boîtes, une liste vide aucune). Dans le tableau de bord, c’est Seulement ces boîtes de réception.
Charges utiles
Chaque événement d’e-mail porte email_id, from, to, subject et created_at, plus tags quand vous avez envoyé l’e-mail avec des étiquettes.
{
"type": "email.failed",
"created_at": "2026-10-13T10:00:02.317Z",
"data": {
"email_id": "3f7b2c71-5274-4246-82f3-57bc1563c276",
"from": "Acme <billing@example.com>",
"to": ["success@simulator.amazonses.com"],
"subject": "Your receipt",
"created_at": "2026-10-13T10:00:02.317Z",
"failed": { "reason": "domain_not_verified" }
}
}
failed.reason |
Ce qui s’est passé |
|---|---|
domain_not_verified |
Le domaine d’envoi n’était pas vérifié au moment où l’e-mail est parti. |
domain_deleted |
Le domaine d’envoi a été supprimé pendant que l’e-mail attendait. |
held_for_review_expired |
L’e-mail a été retenu pour un contrôle de sécurité et n’a pas été libéré en 7 jours. |
team_suspended |
L’équipe a été suspendue et n’a pas été rétablie dans les 7 jours suivant la mise en attente de l’e-mail. |
broadcasts_paused |
Les campagnes de l’équipe ont été mises en pause et n’ont pas repris dans les 7 jours suivant la mise en attente de l’e-mail. |
ses_tenant_paused |
SES a mis l’envoi de l’équipe en pause et ne l’a pas levée en 7 jours. |
body_missing, body_unreadable |
Le contenu enregistré était absent ou illisible, par exemple parce que l’e-mail était encore retenu quand son contenu a dépassé la durée de conservation. |
message_rejected |
Le service de messagerie a refusé le message, par exemple parce qu’il contenait un virus. |
retries_exhausted |
Chaque tentative d’envoi a échoué sur une erreur temporaire. |
send_interrupted |
Un envoi a été interrompu avant d’être confirmé, si bien que l’e-mail est peut-être parti, peut-être pas. Il n’est pas retenté. |
provider_error |
Toute autre erreur qui a arrêté l’envoi. |
{
"type": "email.suppressed",
"created_at": "2026-10-14T09:30:00.912Z",
"data": {
"email_id": "b10f77bb-a99a-48c9-bd0a-a5d2cb1ba4a1",
"from": "Acme <hello@example.com>",
"to": ["success@simulator.amazonses.com"],
"subject": "Your trial ends tomorrow",
"created_at": "2026-10-14T09:30:00.912Z",
"suppressed": {
"type": "OnAccountSuppressionList",
"message": "The recipient is on your suppression list.",
"reason": "recipient_suppressed"
}
}
}
suppressed.reason |
Signification |
|---|---|
recipient_suppressed |
L’adresse figure dans votre liste de suppression. |
contact_unsubscribed |
Le contact est désinscrit pour toute l’équipe. |
domain_unsubscribed |
Le destinataire s’est désinscrit de ce domaine d’envoi. |
topic_unsubscribed |
Le destinataire s’est désinscrit de la thématique de l’e-mail. |
contact_missing, contact_recipient_mismatch |
Le contact a été supprimé, ou son adresse a changé, avant le départ de l’e-mail. |
broadcast_missing, topic_missing |
La campagne ou la thématique a été supprimée avant le départ de l’e-mail. |
ineligible |
Toute autre raison pour laquelle l’e-mail n’était plus éligible. |
Si seuls certains destinataires sont écartés, l’e-mail part aux autres et aucun email.suppressed n’est déclenché. Annuler une campagne ne déclenche rien pour les e-mails qu’elle arrête.
Vérifier la signature
Les envois suivent le schéma Standard Webhooks. Chaque requête porte :
webhook-id: <message id>
webhook-timestamp: <unix seconds>
webhook-signature: v1,<base64 HMAC-SHA256>
Les mêmes valeurs sont aussi envoyées sous les noms svix-id, svix-timestamp et svix-signature, de sorte qu’un gestionnaire écrit pour l’une ou l’autre famille d’en-têtes fonctionne sans changement. Le contenu signé est {webhook-id}.{webhook-timestamp}.{raw body}.
import { Webhook } from "standardwebhooks";
const wh = new Webhook("whsec_...");
const event = wh.verify(rawBody, {
"webhook-id": req.headers["webhook-id"],
"webhook-timestamp": req.headers["webhook-timestamp"],
"webhook-signature": req.headers["webhook-signature"],
});
Vérifiez toujours sur le corps brut de la requête, et rejetez les horodatages anciens.
Secrets
Apportez le vôtre. POST /webhooks accepte signing_secret : whsec_ suivi de la base64 de 24 à 64 octets. Passez le secret que votre récepteur utilise déjà et l’endpoint continue de fonctionner sans redéploiement. Toute autre valeur renvoie 422.
Renouvelez-le. POST /webhooks/{id}/rotate, ou Renouveler le secret dans le tableau de bord, crée un nouveau secret (ou prend celui de signing_secret) et le renvoie. Pendant overlap_hours (24 par défaut, jusqu’à 72), l’ancien secret continue aussi de signer, si bien que chaque envoi porte deux signatures et qu’un récepteur qui a l’un ou l’autre secret le vérifie. Changez de secret côté récepteur à n’importe quel moment de la fenêtre. 0 abandonne l’ancien secret immédiatement, ce qu’il faut faire pour un secret compromis. GET /webhooks/{id} indique la fin de la fenêtre dans previous_secret_expires_at.
curl -X POST "https://api.billionsend.com/webhooks/$WEBHOOK_ID/rotate" \
-H "Authorization: Bearer bs_..." \
-H "Content-Type: application/json" \
-d '{ "overlap_hours": 24 }'
Envoi et nouvelles tentatives
Répondez avec n’importe quel statut 2xx et l’envoi est considéré comme réussi. Chaque endpoint a sa propre file, qui envoie jusqu’à 50 requêtes par seconde.
Une tentative échouée (statut non 2xx, délai dépassé, erreur de connexion) est retentée après 5 secondes, 5 minutes, 30 minutes, 2 heures et 5 heures. Cela fait six tentatives en tout, sur environ 7 heures 35 minutes, et un envoi qui échoue à la sixième est abandonné. Un 429 avec un en-tête Retry-After est respecté (jusqu’à une heure) et ne compte pas comme une tentative. Un événement toujours non distribué 24 heures après sa mise en file est abandonné.
Après 20 envois d’affilée qui ont échoué à toutes leurs tentatives, l’endpoint est désactivé automatiquement (statut auto_disabled) et ne reçoit plus rien jusqu’à ce que vous le réactiviez. Les événements survenus entre-temps ne sont pas rejoués. Les propriétaires de l’équipe reçoivent un e-mail quand les envois commencent à échouer, quand un endpoint est désactivé, et au plus une fois par jour quand son retard dépasse six heures.
La distribution se fait au moins une fois, et les événements ne sont pas distribués dans l’ordre. Un même événement peut arriver plusieurs fois, et les événements peuvent arriver dans un ordre différent de celui dans lequel ils se sont produits : un email.delivered peut arriver avant l’email.sent du même e-mail. Rendez votre gestionnaire idempotent, en vous appuyant sur webhook-id, et ordonnez les événements d’un e-mail selon le created_at de la charge utile (le moment où l’événement s’est produit), jamais selon l’arrivée. Une exception : email.failed avec la raison send_interrupted est une supposition, et un email.sent, email.delivered ou autre résultat pour le même e-mail la remplace même si son created_at est antérieur.
// event : la charge utile vérifiée ; webhookId : l'en-tête webhook-id.
if (await alreadyHandled(webhookId)) return; // un envoi répété
const at = new Date(event.created_at);
const known = await db.emailStatus(event.data.email_id); // { status, at, guess } ou null
const newer = !known || at > known.at || known.guess;
if (newer) {
const guess = event.type === "email.failed" && event.data.failed.reason === "send_interrupted";
await db.setEmailStatus(event.data.email_id, { status: event.type, at, guess });
}
await markHandled(webhookId);
Journal des envois
Ouvrez un endpoint dans le tableau de bord pour voir chaque envoi : l’événement, le contenu, votre réponse et chaque tentative, conservés 30 jours. Vous pouvez appuyer sur Réessayer maintenant sur un envoi, et sur Envoyer un événement de test pour essayer l’endpoint. La page affiche aussi la taille de la file de l’endpoint et depuis combien de temps son plus ancien envoi attend.
Limites
| Free | Starter, Pro, Scale | |
|---|---|---|
| Endpoints de webhook par équipe | 1 | Aucune limite |
Au-delà de la limite, POST /webhooks renvoie 403 plan_limit_reached. Après un retour à un forfait inférieur, les endpoints existants continuent de fonctionner mais vous ne pouvez pas en ajouter. Abonnez chaque endpoint uniquement aux événements dont il a besoin : un endpoint sur « tous les événements » reçoit un contact.created pour chaque contact que vous importez.