Aller au contenu principal

Recevoir les événements

Abonnez une adresse de votre serveur aux événements de vos e-mails, SMS et appels transactionnels : Metaventus l'appelle dès qu'un message change de statut, et vous n'avez plus à interroger l'API.

Ajouter une adresse​

Dans le Centre d'administration › Intégrations & API › Webhooks, cliquez sur Nouvelle adresse, puis renseignez un nom, une adresse en https:// et les événements à recevoir. Le secret de signature s'affiche une seule fois : copiez-le aussitôt.

Le bouton Tester de la fiche envoie un événement webhook.test et affiche la réponse de votre serveur. La fiche liste aussi les derniers envois.

L'offre Découverte comprend une adresse ; les offres payantes n'ont pas de plafond.

Événements​

ÉvénementQuand
email.sentL'e-mail est pris en charge par le service d'envoi.
email.deliveredLe serveur de messagerie du destinataire l'a accepté.
email.failedIl n'a pas été remis (voir error_code).
sms.sentLe SMS est remis à l'opérateur.
sms.deliveredLe téléphone en a accusé réception.
sms.failedIl n'a pas été remis (voir error_code).
voice.sentL'appel est composé.
voice.deliveredLe message a été entendu : décroché (answered) ou déposé sur le répondeur (voicemail_left).
voice.failedL'appel n'a pas abouti (voir outcome).

Ce que vous recevez​

Une requête POST en JSON :

{
"id": "6f1c2c0e-52a7-4c3b-9a0e-2f6f3d7e1b10",
"type": "email.delivered",
"created_at": "2026-11-04T09:00:12Z",
"data": {
"id": "922c2bfd-32ec-4773-b348-63967731e3a7",
"channel": "email",
"to": "marie@exemple.fr",
"from": "contact@votre-domaine.fr",
"subject": "Votre commande est confirmée",
"status": "delivered",
"reference": "commande-20481",
"sent_at": "2026-11-04T09:00:10Z",
"delivered_at": "2026-11-04T09:00:12Z"
}
}

data.id est l'identifiant du message, celui de GET /v1/transactional/messages/{id}. Le contenu du message n'est jamais envoyé.

Pour un appel (voice.*), data porte en plus l'issue (outcome), les touches tapées (digits), la durée depuis le décroché (duration_seconds) et, si l'appel a été mené par un agent vocal, ses réponses (result). Voir Passer un appel transactionnel.

En-têteValeur
X-Metaventus-EventLe type d'événement.
X-Metaventus-DeliveryL'identifiant de cet envoi : il change d'une adresse à l'autre et reste le même d'un essai à l'autre.
X-Metaventus-TimestampL'heure de l'essai, en secondes Unix.
X-Metaventus-Signaturev1= suivi de la signature.

Vérifier la signature​

Calculez un HMAC-SHA256 de horodatage.corps avec votre secret, sur le corps brut de la requête, et comparez-le à la signature reçue. Refusez aussi les envois trop anciens.

import crypto from "node:crypto";

function estAuthentique(corpsBrut, entetes, secret) {
const horodatage = entetes["x-metaventus-timestamp"];
const recue = (entetes["x-metaventus-signature"] || "").replace("v1=", "");
const attendue = crypto.createHmac("sha256", secret).update(`${horodatage}.${corpsBrut}`).digest("hex");
const recent = Math.abs(Date.now() / 1000 - Number(horodatage)) < 300;
return recent && recue.length === attendue.length
&& crypto.timingSafeEqual(Buffer.from(recue), Buffer.from(attendue));
}

Répondre et nouvelles tentatives​

Répondez par un code 2xx en moins de 10 secondes, et traitez l'événement ensuite. Tout autre résultat vaut échec : Metaventus retente après 1 minute, 5 minutes, 30 minutes, 2 heures, puis 6 heures, soit six essais au total. Les redirections ne sont suivies que vers des adresses publiques.

Les événements peuvent arriver en double ou dans le désordre : dédoublonnez sur X-Metaventus-Delivery et fiez-vous à data.status plutôt qu'à l'ordre d'arrivée.

Une adresse désactivée ou supprimée ne reçoit plus rien, et ses envois en attente sont annulés.