Event catalog

Every event travels in the same envelope, { "event", "data", "sent_at" }, signed the same way. Webhooks covers the setup, the signature, the timeout and the retries; this page covers what each event means.

Index

Event	Fires when	Reaches
`verification.verified`	A `check` matched the code.	The application’s webhook; the partner webhook when subscribed
`verification.failed`	The attempts ran out without a matching code.	The application’s webhook; the partner webhook when subscribed
`verification.expired`	The code expired unused.	The application’s webhook; the partner webhook when subscribed
`message.sent`	Meta accepted a WhatsApp message.	The application’s webhook
`message.delivered`	The message reached the phone.	The application’s webhook
`message.read`	The message was read.	The application’s webhook
`message.failed`	Meta reported the message as failed.	The application’s webhook
`service.approved`	A client application was approved.	The partner webhook, by default
`service.rejected`	A client application was rejected.	The partner webhook, by default
`service.suspended`	A client application was suspended.	The partner webhook, by default
`service.resumed`	A client application was switched back on.	The partner webhook, by default
`service.paused`	The protection guard paused a client application.	The partner webhook, by default
`service.unpaused`	The pause was lifted.	The partner webhook, by default
`service.review_requested`	A brand change sent a client application back to review.	The partner webhook, by default
`service.archived`	A client application was archived.	The partner webhook, by default
`service.restored`	A client application came back from the archive.	The partner webhook, by default
`balance.low`	A charge took the partner’s balance below its threshold.	The partner webhook, by default

Handling any event

Verify the signature first, over the raw body. See Verifying the signature.
Answer 2xx within 5 seconds, then do the work from a queue.
Deduplicate on data.id together with event. The same event can arrive twice.
Do not rely on order. Compare the status in data with what you stored, and never move a record backwards.
Skip test events. An envelope with "test": true is a rehearsal from the console’s Send a test event.
Ignore what you do not know. New events and new data fields can be added; an unknown event deserves a 2xx and nothing else.

Verification events

The data is the verification, in the same shape for the three events. A partner’s copy adds external_id.

Field	Meaning
`id`	The verification’s id, as `start` answered it.
`status`	`verified`, `failed` or `expired`.
`application_id`	The application the code was sent for.
`reference`	Your `reference` from `start`, or `null`.
`channel`	`sms`.
`to`	The destination in E.164, `+9665...`.
`mode`	The key it was sent with: `live`, `test`, `partner` or `partner_test`.
`attempts`	Codes checked so far, right or wrong.
`expires_at`, `verified_at`, `created_at`	ISO 8601 in UTC, with milliseconds. `verified_at` is `null` unless verified.

Codes sent with a test key fire these events too, with mode: "test". Canceling a verification fires no event.

When a code is verified

verification.verified fires on the check that matched the code, once per verification. A later check of the same id answers verified again but sends no second event.

{
  "event": "verification.verified",
  "data": {
    "id": "b7e5c2b0-9c1a-4e2f-8f2a-3a6b0e9d1c44",
    "status": "verified",
    "application_id": "c2a10f3e-8b7a-4d2e-9c1a-1a2b3c4d5e6f",
    "reference": "order-42",
    "channel": "sms",
    "to": "+966551234567",
    "mode": "live",
    "attempts": 1,
    "expires_at": "2026-09-01T12:34:56.789Z",
    "verified_at": "2026-09-01T12:31:02.145Z",
    "created_at": "2026-09-01T12:29:56.789Z"
  },
  "sent_at": "1788265862201"
}

Handle it by marking the action behind reference as confirmed, if your own check call has not done so already. Your server already knows the outcome from the check answer; the event matters when another service makes the check, or as a record.

When a verification fails

verification.failed fires when a wrong code uses the last attempt (max_attempts, 3 by default), or when a check finds the attempts already used. The code can no longer be verified.

{
  "event": "verification.failed",
  "data": {
    "id": "b7e5c2b0-9c1a-4e2f-8f2a-3a6b0e9d1c44",
    "status": "failed",
    "application_id": "c2a10f3e-8b7a-4d2e-9c1a-1a2b3c4d5e6f",
    "reference": "order-42",
    "channel": "sms",
    "to": "+966551234567",
    "mode": "live",
    "attempts": 3,
    "expires_at": "2026-09-01T12:34:56.789Z",
    "verified_at": null,
    "created_at": "2026-09-01T12:29:56.789Z"
  },
  "sent_at": "1788265862201"
}

A send that fails at start (502 send_failed) fires no event: the API answer is the news. Handle it by refusing the action behind reference. Repeated failures from one number or one address are a fraud signal worth logging.

When a code expires

verification.expired fires when a code reaches expires_at unused. A check, a GET /v1/verify/{id} or a cancel that finds the expiry fires it at once; otherwise a sweep finds it, every ten minutes, at least five minutes after the expiry. Expect it up to about a quarter of an hour late.

{
  "event": "verification.expired",
  "data": {
    "id": "b7e5c2b0-9c1a-4e2f-8f2a-3a6b0e9d1c44",
    "status": "expired",
    "application_id": "c2a10f3e-8b7a-4d2e-9c1a-1a2b3c4d5e6f",
    "reference": "order-42",
    "channel": "sms",
    "to": "+966551234567",
    "mode": "live",
    "attempts": 0,
    "expires_at": "2026-09-01T12:34:56.789Z",
    "verified_at": null,
    "created_at": "2026-09-01T12:29:56.789Z"
  },
  "sent_at": "1788265862201"
}

Handle it as a cleanup signal, never as the only timeout: your sign-in screen should count down from expires_at itself.

Message events

message.sent, message.delivered, message.read and message.failed follow a WhatsApp template message sent through Tawked Notifications, from the API or from the console. They reach the application’s own webhook only; a partner’s client applications send no WhatsApp.

{
  "event": "message.delivered",
  "data": {
    "id": "0f4c9c0e-6d2b-4b8a-9c3e-7a1d2e3f4a5b",
    "status": "delivered",
    "application_id": "c2a10f3e-8b7a-4d2e-9c1a-1a2b3c4d5e6f",
    "to": "+9665•• ••• 000",
    "template": "order_received_v1",
    "lang": "ar",
    "reference": "order-1042",
    "price_halalas": 0,
    "error": null,
    "occurred_at": "2026-09-06T09:00:04.512Z",
    "created_at": "2026-09-06T09:00:01.087Z"
  },
  "sent_at": "1788685205201"
}

Field	Meaning
`id`	The message’s id, as `POST /v1/whatsapp/messages` answered it.
`status`	The status this event announces.
`to`	The destination, masked. Match on `id` or `reference`, not on the number.
`template`, `lang`	The template’s name and language.
`reference`	Your `reference` from the send, or `null`.
`price_halalas`	The fee charged for the message.
`error`	On `message.failed`, `{ "code", "message" }` as Meta reported them; `null` otherwise.
`occurred_at`	When the message reached this status.
`created_at`	When the message was sent.

How the events behave:

They arrive within about a minute of Meta reporting the status, and a message is followed for 48 hours after its send.
A status only moves forward: sent, then delivered, then read. A step can be skipped: a message read before its delivery was reported fires message.read alone.
read and failed are final. Nothing follows them.
A send refused at once answers 502 send_failed to the API call and fires no message.failed.

Handle them by storing the latest status per id and ignoring an event whose status is behind the stored one. Sending messages has the status lifecycle.

Partner events

The service.* events and balance.low reach a partner’s webhook only, for the client applications it provisions and for its balance. Each service.* event carries service_id, application_id and the partner’s external_id.

{
  "event": "service.approved",
  "data": {
    "service_id": "c2a10f3e-8b7a-4d2e-9c1a-1a2b3c4d5e6f",
    "application_id": "c2a10f3e-8b7a-4d2e-9c1a-1a2b3c4d5e6f",
    "external_id": "store_88",
    "status": "active"
  },
  "sent_at": "1788265862201"
}

Partner events has each one with its extra fields, the reason_code of a rejection, the subscriptions and the feed to poll instead.

Get started

Verify

Notifications

Webhooks and errors

Partners

Build with AI

Index

Handling any event

Verification events

When a code is verified

When a verification fails

When a code expires

Message events

Partner events

​Index

​Handling any event

​Verification events

​When a code is verified

​When a verification fails

​When a code expires

​Message events

​Partner events

Index

Handling any event

Verification events

When a code is verified

When a verification fails

When a code expires

Message events

Partner events