Webhooks Guide

1. Subscribe to events

Generate an API key in your dashboard, then call POST /v1/webhooks/subscribe from your backend with the URL where you want to receive incoming WhatsApp messages. The response includes a subscription_id and a signing_secret.

Other guarantees of the subscribe call: duplicate subscriptions (same session + trigger_type + filter_id + webhook_url) return HTTP 409 with the existing subscription_id — never a silent re-issue of the secret. The cap of 50 active subscriptions per user returns HTTP 422 WEBHOOK_SUBSCRIPTION_CAP_EXCEEDED. You must own the WhatsApp session you're subscribing to.

2. Verify the signature on every delivery

Every outbound delivery includes two headers:

• X-WhatsScale-Signature: sha256=<hex> — HMAC-SHA-256 over the raw request body using your subscription's signing_secret
• X-WhatsScale-Timestamp: <unix-epoch-seconds> — the worker's clock at sign time, used to bound replay attacks

Verify on every request. Use timing-safe equality (e.g. crypto.timingSafeEqual in Node, hmac.compare_digest in Python) — naive == comparison opens a timing side-channel. Reject events whose timestamp is more than ~5 minutes from your clock to limit replay risk.

HMAC the RAW request body bytes — do not parse-then-restringify the JSON. Key order and whitespace must be exact for the signature to match.

// Node 16+ — built-in crypto, no dependencies.
import crypto from 'node:crypto';

const SECRET = process.env.WEBHOOK_SIGNING_SECRET; // store from subscribe response
const REPLAY_WINDOW_SECONDS = 300;                 // recommended 5 minutes

export function verifyWhatsScaleWebhook(req) {
  const signature = req.headers['x-whatsscale-signature'];
  const timestamp = req.headers['x-whatsscale-timestamp'];
  const rawBody = req.rawBody; // Buffer/string of the raw request body

  if (!signature || !timestamp || !rawBody) return false;

  // 1) Replay window — reject events too far from now
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - Number(timestamp)) > REPLAY_WINDOW_SECONDS) return false;

  // 2) Compute the expected signature
  const expected =
    'sha256=' +
    crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex');

  // 3) Timing-safe compare. Both buffers MUST be the same length —
  // crypto.timingSafeEqual throws otherwise.
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
}

3. Retry schedule and the 4xx-is-permanent rule

Deliveries are at-least-once with exponential backoff. The schedule is applied per delivery; Retry-After headers from your endpoint on HTTP 429 are honoured (floored at the scheduled delay).

Per-attempt timeout is 10 seconds. WhatsScale considers any 2xx response code a successful delivery, regardless of body content — configure your endpoint to return non-2xx (we recommend 500) on processing error so we'll retry.

4. Inspect deliveries

Two endpoints surface delivery state for debugging and audit.

• GET /v1/webhooks/:id/deliveries — all statuses (pending, delivering, succeeded, failed, dead). Filter with ?status=; paginate with the cursor pair before_ts + before_id (both halves required together). Use ?status=succeeded to confirm an event was delivered, or no filter to trace the full lifecycle of a specificevent_id.
• GET /v1/webhooks/:id/failures — the dead-letter queue specifically. Older endpoint, narrower lens — equivalent to /deliveries?status=dead with a different cursor shape (timestamp-only).

To replay a dead delivery (after fixing your endpoint), see section 7. Older dead deliveries can be re-driven without DELETE + re-subscribe.

5. Idempotency keys

At-least-once delivery means your endpoint may receive the same event multiple times. Always dedupe before doing real work.

// Dedupe pattern (any language)
//
// PRIMARY KEY  — event_id     (envelope-level, in JSON body)
//   Stable across retry attempts of the same delivery.
//   Use this to skip duplicates from at-least-once retry.
//
// SECONDARY KEY — data.message_id  (the underlying WhatsApp message ID)
//   Use only if you have multiple webhook subscriptions on the same
//   session — different subscriptions produce different event_id values
//   for the same WhatsApp message.

// Pseudocode — happens in your handler before doing real work
const event = JSON.parse(rawBody);

if (await yourCache.has(event.event_id)) {
  // Already processed this delivery (likely a retry). Acknowledge with
  // 200 so we stop retrying, but skip the side effects.
  return res.status(200).end();
}
await yourCache.set(event.event_id, true, ttlSeconds = 7 * 24 * 3600);

// Now process the event for real.
processIncomingMessage(event.data);
res.status(200).end();

7. Manually replay a dead delivery

When a delivery transitions to dead after exhausting its retry budget, you can replay it once you've fixed the underlying issue (e.g. your endpoint was returning 500 due to a deploy bug). Use POST /v1/webhooks/deliveries/:id/retry.

8. Group management for moderation

The /v1/groups/* endpoints pair with group webhook events to close the moderation loop: receive an event, decide a participant is spam, take action by passing the same data.participant_id back to the relevant action endpoint. No translation needed — participant_id is the same LID format you pass to /participants/remove, /admin/demote, etc.

// 1. Webhook arrives
{
  "event_id": "...",
  "trigger_type": "group",
  "data": {
    "group_id": "[email protected]",
    "participant_id": "263195814002890@lid",
    "participant_name": "Mahidhar",
    "body": "BUY CRYPTO HERE: <spam>",
    ...
  }
}

// 2. Your spam classifier flags it. Kick the sender.
POST /v1/groups/[email protected]/participants/remove
{ "session": "user_xxx",
  "participants": [{ "id": "263195814002890@lid" }] }

9. Known limitation: ingress rate-limit loss