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énement | Quand |
|---|---|
email.sent | L'e-mail est pris en charge par le service d'envoi. |
email.delivered | Le serveur de messagerie du destinataire l'a accepté. |
email.failed | Il n'a pas été remis (voir error_code). |
sms.sent | Le SMS est remis à l'opérateur. |
sms.delivered | Le téléphone en a accusé réception. |
sms.failed | Il n'a pas été remis (voir error_code). |
voice.sent | L'appel est composé. |
voice.delivered | Le message a été entendu : décroché (answered) ou déposé sur le répondeur (voicemail_left). |
voice.failed | L'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ête | Valeur |
|---|---|
X-Metaventus-Event | Le type d'événement. |
X-Metaventus-Delivery | L'identifiant de cet envoi : il change d'une adresse à l'autre et reste le même d'un essai à l'autre. |
X-Metaventus-Timestamp | L'heure de l'essai, en secondes Unix. |
X-Metaventus-Signature | v1= 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.