WEBHOOKS

Events and payloads

wa pushes three kinds of event to the URLs configured per device — one URL per kind, set on the device page. Every request is a signed JSON POST.

Answer 2xx within ten secondsAnything else counts as a failure. wa then retries on a widening backoff — 1, 2, 4, 8, 16 and 32 minutes, then hourly — 29 retries after the first attempt, spanning a little over a day, after which the delivery is dead-lettered and stops. You can replay a dead delivery from the dashboard.

The three events

Field	Type	Description
message.incoming	Incoming URL	The device received a message. Carries the sender, the text, and media metadata — never the media bytes. Its inboxid is what you quote to reply.
message.status	Status URL	A message you sent moved to sent, delivered, read, played or failed. One delivery per transition — WhatsApp only reports a read receipt if the recipient shares them.
device.status	Device URL	The device changed connection state: connecting, qr, connected, disconnected, logged_out. Sent on a real change only, never on a QR refresh.

The envelope

Every delivery has the same four outer fields plus its data, which is what changes with the event.

json

{
  "id": "01JQ8T4Z2KX9V6WQ0N3B7C5D2E",
  "event": "message.status",
  "timestamp": 1772373732,
  "device": "628123456789",
  "data": {
    "device": "628123456789",
    "id": "01JQ8T4Z2K",
    "requestid": "01JQ8T4Z2KREQ",
    "status": "delivered",
    "sent_at": "2026-09-04T09:12:03.000Z",
    "delivered_at": "2026-09-04T09:12:07.000Z",
    "read_at": null
  }
}

Field	Type	Description
id	string	The delivery id. Delivery is at-least-once, so this is your dedupe key — store it and ignore a repeat.
event	string	Which of the three kinds this is. Also sent as the X-Wa-Event header. One of message.incoming · message.status · device.status.
timestamp	integer	The event time in unix seconds — for an incoming message, WhatsApp's own message timestamp. It is part of the signature and identical on every retry, so never reject a delivery for being old.
device	string	The device's own phone number, or its id if it has never paired.
data	object	The payload for this event kind.

Fields are additive: new keys may appear without a version bump, and existing keys never change meaning. Verify the signature before you trust any of it — how to do that.