Skip to main content

Receive events

Subscribe an endpoint on your server to the events of your transactional emails, SMS and calls: Metaventus calls it as soon as a message changes status, so you no longer need to poll the API.

Add an endpoint​

In the Admin center › Integrations & API › Webhooks, click New endpoint, then enter a name, an https:// address and the events to receive. The signing secret is shown only once: copy it right away.

The Test button sends a webhook.test event and shows your server's response. The endpoint panel also lists the latest deliveries.

The Discovery plan includes one endpoint; paid plans have no limit.

Events​

EventWhen
email.sentThe email was taken over by the sending service.
email.deliveredThe recipient's mail server accepted it.
email.failedIt was not delivered (see error_code).
sms.sentThe SMS was handed to the carrier.
sms.deliveredThe phone acknowledged it.
sms.failedIt was not delivered (see error_code).
voice.sentThe call is being dialled.
voice.deliveredThe message was heard: answered (answered) or left on voicemail (voicemail_left).
voice.failedThe call did not succeed (see outcome).

What you receive​

A JSON POST request:

{
"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@example.com",
"from": "contact@your-domain.com",
"subject": "Your order is confirmed",
"status": "delivered",
"reference": "order-20481",
"sent_at": "2026-11-04T09:00:10Z",
"delivered_at": "2026-11-04T09:00:12Z"
}
}

data.id is the message identifier, the one used by GET /v1/transactional/messages/{id}. The message content is never sent.

For a call (voice.*), data also carries the outcome (outcome), the keys pressed (digits), the duration since the call was answered (duration_seconds) and, when a voice agent handled the call, its answers (result). See Place a transactional call.

HeaderValue
X-Metaventus-EventThe event type.
X-Metaventus-DeliveryThe identifier of this delivery: different for each endpoint, the same across attempts.
X-Metaventus-TimestampThe attempt time, in Unix seconds.
X-Metaventus-Signaturev1= followed by the signature.

Verify the signature​

Compute an HMAC-SHA256 of timestamp.body with your secret, on the raw request body, and compare it to the signature received. Also reject sends that are too old.

import crypto from "node:crypto";

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

Responses and retries​

Reply with a 2xx code within 10 seconds, then process the event. Anything else counts as a failure: Metaventus retries after 1 minute, 5 minutes, 30 minutes, 2 hours, then 6 hours, six attempts in total. Redirects are only followed to public addresses.

Events may arrive twice or out of order: deduplicate on X-Metaventus-Delivery and rely on data.status rather than on the order of arrival.

A disabled or deleted endpoint receives nothing more, and its pending deliveries are cancelled.