Webhooks
Engage pushes signed events to your HTTPS endpoint as things happen — inbound messages, delivery statuses, campaign progress and more.
- GET
/v1/webhooks/event-typesAll subscribable eventsdevelopers:manage - GET
/v1/webhooksList endpointsdevelopers:manage - POST
/v1/webhooks{ url, description, events } → 201 { endpoint, secret }developers:manage - GET
/v1/webhooks/{id}developers:manage - PATCH
/v1/webhooks/{id}{ url, description, events, enabled }developers:manage - DELETE
/v1/webhooks/{id}developers:manage - POST
/v1/webhooks/{id}/rotate-secret→ { secret }developers:manage - POST
/v1/webhooks/{id}/testSend a webhook.test event nowdevelopers:manage - GET
/v1/webhooks/{id}/deliveriesDelivery log (?status, ?cursor)developers:manage - POST
/v1/webhooks/deliveries/{id}/replayDeliver again → { delivery_id, status }developers:manage
Setting up an endpoint
Add endpoints in Developers → Webhooks or via the API. Choose the events to receive, or * for all of them (the default). The signing secret (whsec_…) is shown once when the endpoint is created — store it securely, or rotate it later with rotate-secret.
- The URL must use HTTPS and resolve to a public IP address. Redirects aren't followed.
- Up to 20 endpoints per organization.
- Webhooks are included for every account.
Event types
The same list is available from GET /v1/webhooks/event-types. Test sends use the type webhook.test.
Payload
Every event has the same envelope. data depends on the event type.
{
"id": "019a7c3e-8f21-7b4d-9a0c-2e5f6a7b8c9d",
"type": "message.status",
"created_at": "2026-11-11T10:42:07Z",
"org_id": "4d2a…",
"data": {
"id": "0f9b1c7e-5a43-4c1d-9d0e-6f2a8b3c4d51",
"conversation_id": "a81c…",
"phone_number_id": "1c2d…",
"contact_id": "b1e7…",
"campaign_id": null,
"status": "delivered",
"wamid": "wamid.HBgMOTE5ODEyMzQ1Njc4FQIAERgSM0Q…",
"error": null,
"timestamp": "2026-11-11T10:42:07Z"
}
}The envelope id is a UUID unique to the event. On failures, message.status carries error as { code, title, detail } with Meta's error code.
Headers
Verifying signatures
Each request is signed with your endpoint secret. Use the whole secret string, including the whsec_ prefix, as the HMAC key. Compute HMAC_SHA256(secret, t + "." + raw_body) as lowercase hex and compare it with v1 using a constant-time comparison. Reject requests whose timestamp is more than five minutes away from your clock to prevent replay attacks.
Engage-Signature: t=1762857727,v1=5f3c8a2e9b0d4f6a1c7e2b8d3f9a0c4e6b1d7f2a8c3e9b5d0f4a6c2e8b1d7f3aimport crypto from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.ENGAGE_WEBHOOK_SECRET; // whsec_…
const TOLERANCE_SECONDS = 300;
// Use the RAW body — re-serialised JSON will not match the signature.
app.post("/webhooks/engage", express.raw({ type: "application/json" }), (req, res) => {
const header = req.get("Engage-Signature") ?? "";
const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=")));
const t = Number(parts.t);
const v1 = parts.v1 ?? "";
if (!t || Math.abs(Date.now() / 1000 - t) > TOLERANCE_SECONDS) {
return res.status(400).send("stale or missing timestamp");
}
const expected = crypto
.createHmac("sha256", SECRET)
.update(`${t}.${req.body.toString("utf8")}`)
.digest("hex");
const a = Buffer.from(expected, "hex");
const b = Buffer.from(v1, "hex");
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
return res.status(400).send("invalid signature");
}
const event = JSON.parse(req.body.toString("utf8"));
// Deduplicate on event.id — deliveries are at-least-once.
queueForProcessing(event);
res.sendStatus(200); // respond fast; do heavy work asynchronously
});Delivery, retries and replay
- Respond with any
2xxwithin 10 seconds to acknowledge. Do slow work asynchronously. A3xxcounts as a failure. - Failed deliveries (non-2xx, timeouts, connection errors) are retried up to 12 times: after 30 s, 1 min, 5 min, 15 min, 30 min, 1 h, 2 h, 4 h, 6 h, 8 h and 10 h — about 32 hours in total.
- Delivery is at-least-once and events may arrive out of order — deduplicate on the event id and compare timestamps.
- Every attempt is logged with its response code and body under Developers → Webhooks → Deliveries, where you can replay any delivery.
- An endpoint that fails 500 times in a row (any success resets the count) is disabled automatically, pending deliveries to it are dropped, and your team is notified. Re-enable it in the dashboard or with
PATCH{ "enabled": true }.
Testing
Send a webhook.test event to an endpoint with POST /v1/webhooks/{id}/test or the Send test button in the dashboard. The call waits for your server and returns what it answered; test sends are not retried.
{
"delivery_id": "019a7c40-…",
"succeeded": true,
"response_status": 200,
"response_body": "ok",
"duration_ms": 184
}