Webhooks

If you run connections on behalf of your own customers, these two events are what keep you ahead of them. A QR connection can stop working for reasons outside anyone's control — the phone is switched off for a day, WhatsApp is opened on another device, the session simply ages out. When that happens the number goes quiet in both directions, and without an event the first person to notice is your customer.

{
  "event": "connection.disconnected",
  "connection_id": "conn_8f2a…",
  "connection": {
    "id": "conn_8f2a…",
    "phone_number": "393331234567",
    "label": "Studio Rossi",
    "status": "disconnected",
    "needs_reconnect": true,
    "license_status": "active",
    "license_expires": "2027-08-08T09:00:00.000Z",
    "reason": "AUTH_LOST"
  },
  "timestamp": 1786000000000
}

Each event fires once per outage. connection.disconnected is sent at the moment the connection breaks, not on a timer while it stays broken, so a number left unscanned for a week produces one event rather than a stream. connection.connected is sent when it starts working again, and only for a connection you were told had broken.

The QR code is deliberately not in the payload. A WhatsApp QR is a scan-to-login credential: anyone who reads it can take over the session. The event tells you a re-scan is needed — fetch the QR itself over your authenticated GET /api/v1/connections/{id} and show it to the number's owner, exactly as you do during first setup.

reason is a short machine-readable hint for your logs. Treat it as advisory: new values can appear, and the field that drives your UI is needs_reconnect.

Like message.status, these events reach only subscriptions signed up for them. Subscriptions created before Aug 10 2026 keep the list they were created with — re-authorize and they pick up the connection events, or ask support to add them to your existing subscription.

{
  "event": "message.received",
  "connection_id": "conn_8f3a21",
  "message": {
    "id": "cmqj3k2ab0001xyz",
    "wa_id": "[email protected]_3EB0A1B2C3",
    "from": "40700000000",
    "text": "Hello!",
    "media_url": null,
    "media_type": null,
    "timestamp": 1766138640000
  }
}

• •message.id — WASync’s stable message id (the same value GET /messages returns as id); dedupe and join on it (retries can deliver duplicates).
• •message.wa_id — WhatsApp’s own id for the same message (null when unknown). For support and debugging — never a dedupe or join key.
• •from — sender, international digits only (no +).
• •text — null for media-only messages; media_url/media_type — null for text messages or when the media file isn’t publicly fetchable.
• •timestamp — epoch milliseconds (number), not an ISO string.

A message.status delivery updates the state of one of your outgoing messages:

{
  "event": "message.status",
  "connection_id": "conn_8f3a21",
  "message": {
    "id": "cmqj3k2ab0001xyz",
    "wa_id": "[email protected]_3EB0A1B2C3",
    "status": "read",
    "timestamp": 1766138641000
  }
}

• •message.id — WASync’s stable id: the exact value POST /messages returned as messageId. Join on it to update the right message.
• •message.wa_id — WhatsApp’s own id (what POST /messages returns as waMessageId, null when unknown). Support and debugging only.
• •status — one of sent, delivered, read, failed. Only meaningful transitions are delivered; a message may skip straight to a later state. Ordering isn’t guaranteed — treat it as a monotonic ladder and ignore any status that moves a message backwards.

Every delivery carries two headers: X-WASync-Timestamp (epoch ms) and X-WASync-Signature: sha256=<hex> = HMAC-SHA256(`${timestamp}.${rawBody}`, subscription_secret). Compute it over the raw request body (before any JSON parsing) and compare in constant time. The timestamp binds the signature to a moment in time — reject deliveries older than ~5 minutes to block replays.

import crypto from "node:crypto";

// rawBody MUST be the exact bytes you received (verify BEFORE JSON.parse).
export function verifyWASync(headers, rawBody, secret) {
  const ts  = headers["x-wasync-timestamp"];
  const sig = headers["x-wasync-signature"];          // "sha256=<hex>"
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret)
          .update(`${ts}.${rawBody}`)
          .digest("hex");
  return Boolean(sig) &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

import express from "express";
import { verifyWASync } from "./verify.js";

const app = express();

// Capture the RAW body — signature verification needs the exact bytes.
app.post("/webhooks/wasync", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifyWASync(req.headers, req.body.toString("utf8"), process.env.WASYNC_WEBHOOK_SECRET)) {
    return res.status(401).end();
  }
  // Reject stale deliveries (replay window) — 5 minutes is a sane tolerance.
  if (Math.abs(Date.now() - Number(req.headers["x-wasync-timestamp"])) > 5 * 60_000) {
    return res.status(401).end();
  }

  res.status(200).end(); // ACK fast — under 10s — then process async
  const { message } = JSON.parse(req.body.toString("utf8"));
  // ... your logic (dedupe on message.id — retries can deliver duplicates)
});

message.status values form a one-way ladder:

Webhook deliveries are attempted 3 times (immediate, 500 ms, 1 s) and then dropped. There is no long redelivery queue. This means your webhook handler is the fast path, not the guarantee.

To catch everything, run a background reconciliation loop that polls GET /messages?connectionId=… every 30–60 seconds and upserts any rows your webhook handler has not yet seen. Use the cursor for efficient incremental fetches. This loop also backfills status updates that arrived while your webhook endpoint was down.