Webhooks

Les webhooks transmettent les événements d’Emailit à votre application au moment où ils se produisent : vous n’avez pas besoin d’interroger l’API. Utilisez-les pour mettre à jour le statut de livraison dans votre base de données, ne plus écrire aux adresses qui génèrent des rebonds ou des plaintes, réagir aux ouvertures et aux clics, traiter les e-mails entrants ou synchroniser les contacts et les adresses bloquées.

Fonctionnement

1. Vous enregistrez un endpoint. Créez un webhook avec un nom et une URL HTTPS dans le tableau de bord ou via l’API. Emailit génère un secret de signature pour ce webhook.
2. Quelque chose se produit. Emailit enregistre un événement, par exemple email.delivered, et le met en file d’attente pour chaque webhook activé qui est abonné à ce type d’événement et dont le filtre de contenu correspond.
3. Emailit envoie un lot. En quelques secondes, Emailit envoie une requête POST dont le corps est un tableau JSON de 100 événements en attente au maximum, du plus ancien au plus récent. Les requêtes destinées à un même webhook partent une par une.
4. Votre endpoint répond. Tout statut 2xx reçu dans les 30 secondes marque chaque événement du lot comme livré. Toute autre réponse, y compris un timeout ou une redirection, est un échec, et Emailit réessaie d’envoyer le lot pendant environ trois jours.

Chaque requête comporte ces en-têtes :

Pour le format complet, consultez Requêtes de webhook ; pour le code de vérification, consultez Signature des requêtes.

Exemple rapide

Ce gestionnaire Express vérifie la signature, puis traite chaque événement du lot :

import crypto from 'node:crypto';
import express from 'express';

const app = express();

app.post('/webhooks/emailit', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.get('X-Emailit-Timestamp') ?? '';
  const signature = req.get('X-Emailit-Signature') ?? '';
  const expected = crypto
    .createHmac('sha256', process.env.EMAILIT_WEBHOOK_SECRET) // whsec_...
    .update(`${timestamp}.`)
    .update(req.body)
    .digest('hex');

  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  const valid = a.length === b.length && crypto.timingSafeEqual(a, b);
  if (!fresh || !valid) return res.status(401).send('Invalid signature');

  for (const event of JSON.parse(req.body)) {
    switch (event.type) {
      case 'email.delivered':
        console.log(`Delivered ${event.data.object.id} to ${event.data.object.to}`);
        break;
      case 'email.bounced':
      case 'email.complained':
        console.log(`Stop sending to ${event.data.object.to}`);
        break;
    }
  }

  res.sendStatus(200);
});

app.listen(3000);

Événements disponibles

Les webhooks couvrent la livraison des e-mails et les interactions des destinataires (email.delivered, email.bounced, email.clicked, etc.), les e-mails entrants (email.received) et les modifications des domaines, listes de contacts, abonnés, contacts, modèles, adresses bloquées, vérifications d’e-mails et campagnes. Un nouveau webhook créé dans le tableau de bord reçoit tous les événements ; vous pouvez ensuite le limiter à certains types. Consultez Types d’événements.

Sur les forfaits Pro, Business et Custom, un filtre de contenu peut limiter un webhook aux événements qui correspondent à des règles, par exemple uniquement les e-mails destinés à un domaine.

Limites

La page des webhooks indique combien d’endpoints vous utilisez, par exemple 2/3 used. Lorsque vous atteignez la limite, le bouton Add webhook est désactivé jusqu’à ce que vous supprimiez un webhook ou que vous passiez à un forfait supérieur. Chaque webhook peut envoyer 5 événements de test par minute au maximum.

Pour commencer