Annonces5 min de lecture
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.
GParGeorge

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 |
|---|---|
| Accepté pour livraison |
| Programmé pour livraison ultérieure |
| Livré au serveur de messagerie du destinataire |
| Échec définitif (hard bounce) |
| Échec temporaire de livraison |
| Échec dû à une erreur précise |
| Accepté puis rejeté |
| Le destinataire figure sur la liste des adresses bloquées |
| E-mail entrant accepté |
| Plainte pour spam enregistrée |
| Un lien dans l’e-mail a été cliqué |
| 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 :
{
"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-SHA256X-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.
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 |
|---|---|
|
|
|
|
| Signature HMAC-SHA256 |
| Horodatage Unix utilisé dans la signature |
Bonnes pratiques
- Répondez vite : renvoyez immédiatement un code
2xxet 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_idpour dédoublonner. - Vérifiez les signatures : validez toujours l’en-tête
X-Emailit-Signaturepour confirmer que la requête provient d’Emailit. - Protégez-vous contre les attaques par rejeu : vérifiez
X-Emailit-Timestampet 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 : vue d’ensemble et fonctionnement des webhooks
- Types d’événements : liste complète des 36 types d’événements
- Requêtes webhook : format des requêtes, en-têtes et politique de relance
- Signature des requêtes : vérification des signatures, avec des exemples de code dans 5 langages
Pour commencer
Rendez-vous dans la documentation des webhooks pour commencer, ou passez directement à la référence de l’API pour créer votre premier endpoint de webhook.


