Annonce des Webhooks v2

Nous lançons 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 de signature cryptographique et une politique de nouvelle tentative robuste, Webhooks v2 vous offre tout ce dont vous avez besoin pour créer des intégrations fiables pilotées par les événements.

Les nouveautés

36 types d’événements sur 9 ressources

Webhooks v2 couvre 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énements CRUD pour les domaines, audiences, abonnés, contacts, modèles, suppressions, vérifications d’e-mail et listes de vérification d’e-mail, chacun avec les événements .created, .updated et .deleted.

Structure d’événement cohérente

Chaque charge utile de webhook suit la même forme, ce qui facilite la création d’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 avec votre secret webhook en utilisant HMAC-SHA256. 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 recommandons vivement d’utiliser une comparaison sécurisée temporellement (par ex. crypto.timingSafeEqual en Node.js) pour prévenir les attaques temporelles, et de rejeter les requêtes avec des horodatages de plus de quelques minutes pour se 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 de requête.

Nouvelles tentatives automatiques avec backoff exponentiel

Si votre endpoint ne répond pas avec un code 2xx dans les 30 secondes, Emailit effectue automatiquement de nouvelles tentatives :

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 :

Bonnes pratiques

• Répondez rapidement — Retournez un code 2xx immédiatement et traitez la charge utile de manière asynchrone dans une tâche en arrière-plan.
• Gérez les doublons — Le même événement peut être livré plusieurs fois lors des nouvelles tentatives. Utilisez event_id pour dédupliquer.
• 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 le X-Emailit-Timestamp et rejetez les requêtes de plus de quelques minutes.

Documentation complète

Nous avons publié une documentation complète pour Webhooks v2 avec des exemples détaillés de charges utiles et des descriptions de 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 de requête, en-têtes et politique de nouvelle tentative
• Signature de requête — Vérification de signature avec exemples de code en 5 langages

Pour commencer

Rendez-vous sur la documentation Webhooks pour commencer, ou allez directement à la Référence API pour créer votre premier endpoint webhook.