# Les Webhooks v2 sont là

> Les Webhooks v2 sont arrivés : 36 types d’événements, signatures HMAC-SHA256, nouvelles tentatives automatiques et documentation complète pour chaque payload.

2026-02-26 · George (https://x.com/thegeorge, https://www.linkedin.com/in/jiri-zizka/)

Nous lançons les **Webhooks v2**, une refonte complète de la façon dont Emailit transmet les notifications d’événements en temps réel à vos applications. Avec 36 types d’événements répartis sur 9 catégories de ressources, la vérification cryptographique des signatures et une politique de relance robuste, les Webhooks v2 vous donnent tout ce qu’il faut pour bâtir des intégrations fiables, pilotées par les événements.

## Les nouveautés

### 36 types d’événements sur 9 ressources

Les Webhooks v2 couvrent toutes les ressources d’Emailit. Vous pouvez vous abonner précisément aux événements qui vous intéressent ou utiliser `all_events` pour tout recevoir.

**Les événements d’e-mail** suivent l’intégralité du cycle de livraison :

| Événement | Description |
| --- | --- |
| `email.accepted` | Accepté pour livraison |
| `email.scheduled` | Programmé pour livraison ultérieure |
| `email.delivered` | Livré au serveur de messagerie du destinataire |
| `email.bounced` | Échec définitif (hard bounce) |
| `email.attempted` | Échec temporaire de livraison |
| `email.failed` | Échec dû à une erreur précise |
| `email.rejected` | Accepté puis rejeté |
| `email.suppressed` | Le destinataire figure sur la liste des adresses bloquées |
| `email.received` | E-mail entrant accepté |
| `email.complained` | Plainte pour spam enregistrée |
| `email.clicked` | Un lien dans l’e-mail a été cliqué |
| `email.loaded` | Le contenu de l’e-mail a été chargé (ouvert) |

**Des événements CRUD** pour les domaines, les listes de contacts, les abonnés, les contacts, les modèles, les adresses bloquées, les vérifications d’e-mails et les listes de vérification, chacun avec des événements `.created`, `.updated` et `.deleted`.

### Structure d’événement cohérente

Chaque payload de webhook suit la même structure : il est donc simple d’écrire un gestionnaire unique pour tous les événements :

```json
{
  "event_id": "evt_2bH7kNwP5mQaV1sXgIdKe6pZr",
  "type": "email.delivered",
  "data": {
    "object": {
      "id": "em_4yM2nTvR8oPcX3uZiKeLg7sB",
      "object": "email",
      ...
    }
  }
}
```

L’`event_id` identifie de manière unique chaque événement, `type` vous indique ce qui s’est passé, et `data.object` contient la ressource complète au moment de l’événement.

### Vérification de signature HMAC-SHA256

Chaque requête webhook est signée en HMAC-SHA256 avec le secret de votre webhook. La signature est calculée sur `{timestamp}.{rawBody}`, vous permettant de vérifier à la fois l’authenticité et la fraîcheur en une seule étape.

Chaque requête inclut deux en-têtes :

- `X-Emailit-Signature` : le condensé hexadécimal HMAC-SHA256
- `X-Emailit-Timestamp` : l’horodatage Unix utilisé dans la signature

Nous vous recommandons vivement d’utiliser une comparaison à temps constant (par exemple `crypto.timingSafeEqual` en Node.js) pour éviter les attaques temporelles, et de rejeter les requêtes dont l’horodatage date de plus de quelques minutes pour vous protéger contre les attaques par rejeu.

Des exemples de vérification complets en Node.js, Python, PHP, Ruby et Go sont disponibles dans la documentation [Signature des requêtes](https://emailit.com/docs/webhooks/request-signature).

### Relances automatiques à intervalles exponentiels

Si votre endpoint ne répond pas par un code `2xx` dans les 30 secondes, Emailit relance automatiquement la requête :

| Tentative | Délai |
| --- | --- |
| 0 | 5 secondes |
| 1 | 5 minutes |
| 2 | 30 minutes |
| 3 | 2 heures |
| 4 | 5 heures |
| 5 | 10 heures |
| 6 | 24 heures |

Soit 7 tentatives au total sur environ 41 heures. Après la dernière tentative, le webhook est automatiquement désactivé. Vous pouvez le réactiver depuis le tableau de bord à tout moment.

## Format de requête

Toutes les requêtes webhook sont des `POST` avec un corps JSON. Chaque requête inclut ces en-têtes :

| En-tête | Description |
| --- | --- |
| `Content-Type` | `application/json` |
| `User-Agent` | `Emailit-Webhook/1.0` |
| `X-Emailit-Signature` | Signature HMAC-SHA256 |
| `X-Emailit-Timestamp` | Horodatage Unix utilisé dans la signature |

## Bonnes pratiques

- **Répondez vite** : renvoyez immédiatement un code `2xx` et traitez le payload de manière asynchrone, dans une tâche en arrière-plan.
- **Gérez les doublons** : un même événement peut être livré plusieurs fois lors des relances. Utilisez `event_id` pour dédoublonner.
- **Vérifiez les signatures** : validez toujours l’en-tête `X-Emailit-Signature` pour confirmer que la requête provient d’Emailit.
- **Protégez-vous contre les attaques par rejeu** : vérifiez `X-Emailit-Timestamp` et rejetez les requêtes de plus de quelques minutes.

## Documentation complète

Nous avons publié une documentation complète des Webhooks v2, avec des exemples de payloads détaillés et la description des champs pour les 36 événements :

- [Introduction](https://emailit.com/docs/webhooks) : vue d’ensemble et fonctionnement des webhooks
- [Types d’événements](https://emailit.com/docs/webhooks/event-types) : liste complète des 36 types d’événements
- [Requêtes webhook](https://emailit.com/docs/webhooks/webhook-requests) : format des requêtes, en-têtes et politique de relance
- [Signature des requêtes](https://emailit.com/docs/webhooks/request-signature) : vérification des signatures, avec des exemples de code dans 5 langages

## Pour commencer

Rendez-vous dans la [documentation des webhooks](https://emailit.com/docs/webhooks) pour commencer, ou passez directement à la [référence de l’API](https://emailit.com/docs/api-reference/webhooks/create) pour créer votre premier endpoint de webhook.

---

Source: https://emailit.com/fr/blog/annonce-webhooks-v2/
