Webhooks

Événements de livraison d'e-mails

Recevez en temps réel des notifications sur l'état de livraison de vos e-mails. Configurez votre URL de webhook dans le dashboard. Tous les événements sont signés avec HMAC-SHA256 pour plus de sécurité.

POSThttps://your-server.com/webhook/email/delivery
!

Vérifiez toujours la signature du webhook. Générez le secret de votre webhook dans le dashboard et utilisez-le pour vérifier les requêtes entrantes. Calculez le HMAC sur le corps brut de la requête, et non sur un JSON resérialisé.

Démarrage rapide

Un listener qui vérifie la signature puis traite l'événement. Répondez avec un statut 2xx dès que l'événement est accepté.

const express = require('express');
const crypto = require('crypto');

const app = express();
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

function verifySignature(rawBody, signature) {
  if (!signature) return false;

  const expected = 'sha256=' + crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(rawBody)
    .digest('hex');

  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  // timingSafeEqual throws when the lengths differ
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// express.raw keeps the body as a Buffer, exactly as it was sent
app.post('/webhook/email/delivery', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifySignature(req.body, req.headers['x-webhook-signature'])) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { event, emailId, data } = JSON.parse(req.body.toString('utf8'));

  console.log('[Email Delivery] ' + event + ' - ' + emailId);

  if (event === 'delivered') {
    console.log('   Recipient: ' + data.recipientEmail);
  } else if (event === 'bounced') {
    console.log('   Reason: ' + data.reason);
  }

  res.status(200).json({ received: true });
});

app.listen(3001, () => {
  console.log('Email delivery webhook listener on port 3001');
  console.log('   POST /webhook/email/delivery');
});

En-têtes

  • X-Webhook-Signaturestringobligatoire

    Signature HMAC-SHA256 du corps de la requête. Format : sha256=hex_digest

Tester avec ngrok

Exposez votre listener local sur internet et enregistrez l'URL générée comme URL de webhook dans le dashboard.

ngrok http 3001
# Your webhook URL:
# https://abc123.ngrok.io/webhook/email/delivery

Événements

Chaque événement est un objet JSON avec event, timestamp et un objet data. Ouvrez un événement pour voir son payload complet et ses champs.

Votre endpoint échoue trop souvent ? Consultez Lister les webhooks pour vérifier son statut, ou Relancer tous les échecs pour remettre en file d'attente ce qui a été manqué.