---
title: Webhooks
description: Des envois d'événements signés vers votre endpoint, avec nouvelles tentatives et un journal des envois.
seo:
  title: Webhooks email
ai:
  exclude: true
---

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](/docs/fr/sdks) vérifient les envois avec `verifyWebhook` (Node.js) et `verify_webhook` (Python).

```sh
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](/docs/fr/concepts/suppressions)), `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](/docs/fr/concepts/domains)). |
| `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](/docs/fr/receiving). `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](/docs/fr/concepts/unsubscribes) pour le sens de `domain_id`.

### Événements de boîte de réception

Les [boîtes de réception](/docs/fr/inboxes) 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.

```json title="email.failed"
{
  "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. |

```json title="email.suppressed"
{
  "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](https://www.standardwebhooks.com). 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}`.

```ts
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`.

```sh
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.

```ts
// 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.
