Référence

Webhooks

Recevez les événements en temps réel, pour que votre système sache toujours ce qu'est devenu chaque message. Vérifiez chaque requête grâce à sa signature.

Fonctionnement des webhooks

Enregistrez un endpoint HTTPS dans le tableau de bord et choisissez les événements à recevoir. Quand il arrive quelque chose à un message, MigoSMTP envoie une requête POST avec un corps JSON à votre endpoint.

Types d'événements

Abonnez-vous uniquement aux événements dont votre système a besoin. Chaque événement contient l'identifiant du message, le destinataire et un horodatage, pour que vous puissiez le rattacher au message envoyé.

Exemple de charge utile

Les charges utiles sont du JSON envoyé par une requête POST. Les valeurs ci-dessous ne sont que des exemples.

{
  "event": "delivered",
  "message_id": "msg_123",
  "recipient": "you@example.com",
  "timestamp": "2026-01-15T10:30:00Z"
}

Vérifiez la signature

Toute personne connaissant votre URL pourrait y envoyer des requêtes ; vérifiez donc chaque requête. Calculez un HMAC du corps brut de la requête avec votre secret de signature et comparez-le à la valeur de l'en-tête de signature avec une comparaison en temps constant. Rejetez les requêtes qui ne correspondent pas. Le nom de l'en-tête et l'algorithme sont affichés avec votre secret de signature dans le tableau de bord.

const crypto = require("crypto");
function valid(rawBody, received, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(received);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Répondez rapidement

Renvoyez un statut 2xx dès que vous avez enregistré l'événement, et faites le vrai travail ensuite dans une file. Un endpoint lent ou défaillant provoque des nouvelles tentatives et peut retarder vos autres événements.

Prévoyez des doublons et des événements dans le désordre

Les livraisons échouées sont réessayées : un même événement peut donc arriver plusieurs fois, et les événements peuvent arriver dans le désordre. Utilisez l'identifiant du message et le type d'événement pour rendre votre gestionnaire idempotent, et l'horodatage de l'événement plutôt que l'heure d'arrivée.

Testez avant de vous y fier

Pointez l'endpoint vers un inspecteur de requêtes ou un tunnel vers votre machine de développement, envoyez un message de test et confirmez que vous pouvez vérifier la signature sur du trafic réel.

ÉvénementSignification

deliveredLe serveur destinataire a accepté le message.

bouncedLe message n'a pas pu être livré. Cessez d'écrire à cette adresse, sauf s'il s'agissait d'un problème temporaire.

deferredÉchec temporaire ; la livraison sera réessayée.

openedLe destinataire a ouvert le message. Considérez-le comme un signal approximatif, car les applications de messagerie peuvent précharger les images.

clickedLe destinataire a cliqué sur un lien suivi.

complainedLe destinataire a signalé le message comme spam. Cessez d'écrire à cette adresse.

Cette page vous a-t-elle été utile ?Contacter le support