Aller au contenu
Esc
↑↓naviguer↵ouvrir⌘Japerçu
Sur cette page

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.

Cette page vous a-t-elle été utile ?