Aller au contenu

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.

GPar

Les Webhooks v2 sont là

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 :

{
  "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.

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 :

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.

Partager

Essayez ce que vous venez de lire.

3 000 e-⁠mails gratuits par mois. Sans carte bancaire.

3 000 e-⁠mails gratuits par mois · Sans carte bancaire