Send WhatsApp events to your server with webhooks

Outbound webhooks let WACRM push a WhatsApp event to a URL you control, signed so you can confirm it really came from WACRM, instead of your server polling the API for changes. This guide covers the two places that manage the same webhook endpoints — Workspace’s Settings → Apps & Connectors → Webhooks screen and the Core API directly — and says plainly which events, retries and limits exist today.

What you need before you start

• A WACRM Workspace account with at least one project, on the Advanced plan or higher (owner access, to manage webhooks from Workspace).
• A server you control that can receive an HTTPS POST request and respond with a 2xx status.
• For the API steps only: curl (or any HTTP client that can set a header), and an API key with the wa_webhooks:read/wa_webhooks:write scopes from Developer / API & MCP.

Add a webhook endpoint in Workspace

1. Open Settings → Apps & Connectors → Webhooks. This screen is owner-only — a team member without owner access won’t see a way to add or change an endpoint here.
2. Click Add endpoint.
3. Enter your server’s Endpoint URL — it must start with https://, and it’s refused if it resolves to a private, loopback, link-local or other reserved address (checked again at delivery time, so a hostname that gets repointed after you create it is still caught).
4. Tick the Events to send you want: message.inbound (a WhatsApp message arrived) and/or message.status (a message’s delivery status changed). These are the only two events available today.
5. Click Create endpoint.

A Your new webhook signing secret dialog opens immediately after create, showing the secret exactly once — copy it now. WACRM never stores or logs a readable copy of it, and can’t show that same secret again; if you lose it, rotate it for a new one (see below).

Verify the signature on your server

Every delivery — a real event, a redelivery or a test send — carries an X-WACRM-Signature header shaped like t=<unix timestamp>,v1=<hex HMAC-SHA256 of "<t>.<raw body>", signed with your endpoint's secret>. Recompute the same HMAC over the exact raw request body and compare it to v1 before trusting the payload; never trust the body alone. This is the same signed-webhook pattern most webhook providers use (see the HMAC and webhooks sources below) — with placeholders standing in for your own secret, never a real one:

const crypto = require('crypto');

// header: the raw X-WACRM-Signature value; rawBody: the exact bytes WACRM sent,
// not a re-serialized JSON.parse(body) — whitespace differences break the HMAC.
function isValidWebhookSignature(header, rawBody, endpointSecret) {
  const [tPart, v1Part] = header.split(',');
  const timestamp = tPart.split('=')[1];
  const expected = crypto
    .createHmac('sha256', endpointSecret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');
  return v1Part === `v1=${expected}`;
}

Send a test, read Deliveries, and redeliver a failed one

1. From the endpoint’s row, click Send test. This sends exactly one signed webhook.test event through the same delivery path, SSRF check and signature as a real event — useful for confirming your server validates the signature correctly before you wire up real traffic. It’s capped at 5 test sends per endpoint per minute; a 6th within the same minute is rejected.
2. Click Deliveries to open the list of everything sent to this endpoint — event, status, HTTP status, attempts and the last attempt’s time, newest first. Deliveries are kept for 30 days and then removed.
3. For a delivery marked Failed, click Redeliver. This resends the exact same payload as a brand-new delivery — the original failed row is kept as-is, so you still have a record of what happened the first time.

An endpoint that’s turned off (Active switched off) refuses both Send test and Redeliver outright — turn it back on first.

Rotate the secret

If your secret leaks, or you just want a fresh one, click Rotate secret on the endpoint’s row. The same one-time reveal dialog opens with the new secret — copy it immediately, since the old secret stops verifying deliveries right away, with no overlap window for in-flight signatures. Update your server with the new secret before rotating, or your verification will start failing the moment you confirm.

Do the same thing through the API

Everything above is also reachable directly, scoped to wa_webhooks:read/wa_webhooks:write — tick both under Restrict what this key can do (advanced) → WhatsApp CRM scopes when you mint a key in Developer / API & MCP. Neither scope is granted by default to any key, since an endpoint receives your project’s live message content.

curl -s -X POST https://api.wacrm.ai/v1/webhook-endpoints \
  -H "Authorization: Bearer sk_live_your_scoped_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.com/webhook", "events": ["message.inbound", "message.status"]}'

{
  "data": {
    "id": "7e9b9b7a-...-endpoint-uuid",
    "url": "https://your-server.com/webhook",
    "events": ["message.inbound", "message.status"],
    "active": true,
    "created_at": "2026-11-08T09:00:00+00:00",
    "secret": "whsec_your_one_time_secret"
  }
}

secret is only ever present in this create response and in a rotate-secret response — every other call, including re-fetching the same endpoint, omits it entirely. A project can have at most 20 endpoints; creating a 21st answers 409 {"error": {"code": "endpoint_limit_reached"}}. PATCH takes whichever of url/events/ active you’re changing (at least one is required) and never returns a secret. A redelivered delivery or a test send against an endpoint with active: false answers 409 {"error": {"code": "endpoint_inactive"}} before anything else runs; a 6th test send in the same minute answers 429 {"error": {"code": "rate_limited"}}.

What works today vs. not yet

Ready to try this against your own project? Request early access to get a Workspace, or see pricing first if you’re still comparing plans. For more how-tos like this one, browse the full guides list.