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
| Event | When |
|---|---|
email.sent | The email was taken over by the sending service. |
email.delivered | The recipient's mail server accepted it. |
email.failed | It was not delivered (see error_code). |
sms.sent | The SMS was handed to the carrier. |
sms.delivered | The phone acknowledged it. |
sms.failed | It was not delivered (see error_code). |
voice.sent | The call is being dialled. |
voice.delivered | The message was heard: answered (answered) or left on voicemail (voicemail_left). |
voice.failed | The 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.
| Header | Value |
|---|---|
X-Metaventus-Event | The event type. |
X-Metaventus-Delivery | The identifier of this delivery: different for each endpoint, the same across attempts. |
X-Metaventus-Timestamp | The attempt time, in Unix seconds. |
X-Metaventus-Signature | v1= 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.