Skip to content

Webhooks

Engage pushes signed events to your HTTPS endpoint as things happen — inbound messages, delivery statuses, campaign progress and more.

Endpoints

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

EventSent when
message.receivedA customer sent you a message (any type, including button and list replies)
message.statusAn outbound message was sent, delivered, read, played or failed
message.createdA message was sent from the WhatsApp Business app on a coexistence number
conversation.updatedA conversation was assigned, resolved, reopened or got a new message
contact.createdA new contact was created
contact.consent_changedA contact opted in or out
contact.tag_addedA tag was added to a contact
contact.tag_removedA tag was removed from a contact
contact.attribute_changedA custom attribute changed
contact.identity_changedA contact changed phone number or WhatsApp user id
campaign.completedA campaign finished sending
template.statusMeta approved, rejected, paused or disabled a template
template.qualityA template's quality rating changed
number.qualityA number's quality rating, throughput or messaging limit changed
account.updatedWhatsApp account alerts, reviews and capability changes

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

HeaderValue
Engage-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256>
Engage-Event-IdSame as the payload id — use it to deduplicate
Engage-Event-TypeThe event type
Engage-Delivery-IdThis delivery attempt's id, as shown in the delivery log
User-AgentEngage-Webhooks/1.0 (+https://engage.swastik.ai)
Content-Typeapplication/json

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.

Example header
Engage-Signature: t=1762857727,v1=5f3c8a2e9b0d4f6a1c7e2b8d3f9a0c4e6b1d7f2a8c3e9b5d0f4a6c2e8b1d7f3a
import 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
});
Verify against the raw body
Frameworks that parse JSON before your handler runs will change whitespace and key order. Capture the raw request bytes for verification.

Delivery, retries and replay

  • Respond with any 2xx within 10 seconds to acknowledge. Do slow work asynchronously. A 3xx counts 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.

Response
{
  "delivery_id": "019a7c40-…",
  "succeeded": true,
  "response_status": 200,
  "response_body": "ok",
  "duration_ms": 184
}
Something unclear or missing on this page? Tell us at contact@swastik.ai