Skip to main content
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

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 the tawked-webhook-id header: one id per event, the same on every retry and on a delivery sent again. On the body, use event, data.id and data.recipient.id when recipient is present, else event and data.id. 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. 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.
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.
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.
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.
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.

Email events

email.delivered, email.bounced, email.complained and email.failed follow a message sent through Tawked Email, one event per recipient, and so do the others below, which an endpoint receives once its owner adds them. They reach the application’s own webhook only, never a partner’s. A message sent in the original shape (one to string, no cc, bcc, tags or scheduled_at) has one recipient and one event per outcome, as below:
Email events carry type (the same as event) and timestamp (when it happened) after data; a test key’s events add "mode": "test" and reach only endpoints that receive test events. For a message of several recipients, data adds recipient and tags after to, and to, error, bounce and occurred_at are that recipient’s:
How the events behave:
  • One outcome per recipient, one event. email.delivered comes once for each recipient; a bounce or a complaint can follow it later, when a mailbox refuses or reports a message it first accepted.
  • A message that could not be sent after its 202 (a domain that lost its record, a refusal at the sending service, 12 hours in the queue) fires email.failed with its reason in error.code, once per recipient of a message of several; its price is refunded. A pause after the 202 fires nothing at first: the message stays queued and is sent if the pause lifts within 12 hours of its time, else it fails with queue_expired.
  • A suppressed address is skipped at the send and fires email.suppressed to the endpoints that chose it. A recipient suppressed between the send and its time fires email.failed with recipient_suppressed and email.suppressed: handle one of them. email.failed for this cause is kept until a dated deprecation announced at least 90 days ahead. A send in the original shape to a suppressed address is refused with 422 recipient_suppressed: no message, no event.
  • Dedupe on tawked-webhook-id, or on event, data.id and data.recipient.id.
Handle them by storing the outcome per id, and by stopping mail to an address whose email.bounced is Permanent or that complained: Tawked refuses it from then on anyway. Sending email has the statuses.

More e-mail events

An endpoint receives these, and the domain and suppression events below, only once its owner adds them by name, in the console or in events; a new endpoint starts without them. Each carries the message’s fields as above, and its own object after bounce: A click on a tracked link:
An open or a click of a message of several recipients counts for the whole message: to and recipient are null and recipients lists its addresses, since one pixel and one set of links serve them all. Open and click tracking says what each records and where it is kept.

Domain events

domain.created, domain.verified, domain.failed and domain.removed follow the application’s sending domains. data is the domain object, with previous_state and reason (null, dkim_record_missing, timed_out, removed_by_client or released_by_team).

Suppression events

suppression.added and suppression.removed follow the account’s suppression list. An entry with no application reaches every application of the account that has Email. suppression.added’s data: suppression.removed’s data has no source and adds how it was lifted:

Received email

email.received tells you an email reached one of the application’s receiving addresses, once per email, after Tawked read it (data.parse is ready) or could not (failed). Its envelope is the Email group’s, with type and timestamp (when the email arrived) after data. It carries metadata only: the list item of GET /v1/email/received, then envelope_from, message_id, in_reply_to, authentication, parse and the attachments’ facts, never a body, a header or a download link. Fetch GET /v1/email/received/{id} with a key that holds email:inbound when you need the content. An endpoint receives it only once you tick it; the test message Tawked sends to a new address carries "test": true in the envelope. See Receiving email.

Campaign events

campaign.started, campaign.paused and campaign.completed follow a WhatsApp campaign sent from the console or the Account API: three deliveries a campaign, whatever its size. A new endpoint of an application that sends WhatsApp starts with them ticked; an endpoint made before they existed receives them once you tick them.
How the events behave:
  • campaign.completed is sent once in a campaign’s life, even when a later retry or follow-up reopens it.
  • A paused campaign that resumes sends no event of its own; the next campaign.paused or campaign.completed follows.
  • The figures keep moving after campaign.completed: orders are attributed for days. Read them from the console or the Account API.
  • Each message’s statuses (message.*) are not sent for campaign messages unless the application turns them on (Campaign settings in the console, or campaigns.settings.update with campaign_message_webhooks: true on the Account API): a campaign of 5,000 customers is about 15,000 deliveries. The statuses of every other message are unchanged.

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.
Partner events has each one with its extra fields, the reason_code of a rejection, the subscriptions and the feed to poll instead.
Last modified on October 29, 2026