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é.
https://your-server.com/webhook/email/deliveryVé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-SignaturestringobligatoireSignature 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.
Livraison
Ce qui arrive à un e-mail sur le chemin de la boîte de réception.
queuedEnvoyé une fois lorsqu'un e-mail entre dans la file de livraison, pour tous les e-mails : API, SMTP et campagnes. Envoyé à nouveau lorsque l'e-mail est déplacé vers une autre IP ou un autre serveur pour une nouvelle tentative.
processingEnvoyé lorsque l'e-mail a passé nos contrôles et est sur le point d'être envoyé au serveur de destination.
deliveredEnvoyé lorsque le serveur de messagerie de destination accepte l'e-mail.
bouncedEnvoyé lorsqu'un e-mail est rejeté définitivement : l'adresse n'existe pas, le domaine ne peut pas recevoir d'e-mails ou nous avons arrêté d'essayer.
spamEnvoyé lorsque le serveur de messagerie de destination refuse l'e-mail comme spam ou pour une raison de politique pendant la livraison.
retryingEnvoyé chaque fois qu'un e-mail n'a pas encore pu être livré et fera l'objet d'une nouvelle tentative.
failedEnvoyé lorsque nous abandonnons un e-mail après épuisement de ses nouvelles tentatives.
return_pathEnvoyé lorsqu'un message de bounce (DSN) arrive plus tard, après que le serveur de destination a d'abord accepté l'e-mail. Un échec fait passer l'e-mail à bounced. Un avis de retard ou de livraison envoie seulement cet événement.
Suivi
Ce que fait le destinataire une fois l'e-mail arrivé.
email_openedEnvoyé lorsqu'un destinataire ouvre un e-mail avec le suivi des ouvertures activé. Inclut l'appareil, l'IP, le pays et si l'ouverture est passée par un proxy.
email_clickedEnvoyé lorsqu'un destinataire clique sur un lien dans un e-mail avec le suivi des clics activé. Inclut l'URL et s'il s'agissait du premier clic.
unsubscribeEnvoyé lorsqu'un destinataire se désabonne depuis l'un de vos e-mails : sur la page de désabonnement, avec le bouton en un clic de sa messagerie (Gmail, Yahoo, Outlook) ou par e-mail via l'en-tête List-Unsubscribe.
tracking_preferences_updatedEnvoyé lorsqu'un destinataire modifie son choix de suivi des ouvertures ou des clics sur la page des préférences de suivi. Il continue de recevoir vos e-mails : ce n'est pas un désabonnement.
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é.