{ "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
2xxwithin 5 seconds, then do the work from a queue. - Deduplicate on the
tawked-webhook-idheader: one id per event, the same on every retry and on a delivery sent again. On the body, useevent,data.idanddata.recipient.idwhenrecipientis present, elseeventanddata.id. The same event can arrive twice. - Do not rely on order. Compare the status in
datawith what you stored, and never move a record backwards. - Skip test events. An envelope with
"test": trueis a rehearsal from the console’s Send a test event. - Ignore what you do not know. New events and new
datafields can be added; an unknown event deserves a2xxand nothing else.
Verification events
The data is the verification, in the same shape for the three events. A partner’s copy addsexternal_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.
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.
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.
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, thendelivered, thenread. A step can be skipped: a message read before its delivery was reported firesmessage.readalone. readandfailedare final. Nothing follows them.- A send refused at once answers
502 send_failedto the API call and fires nomessage.failed.
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:
- One outcome per recipient, one event.
email.deliveredcomes 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) firesemail.failedwith its reason inerror.code, once per recipient of a message of several; its price is refunded. A pause after the202fires nothing at first: the message staysqueuedand is sent if the pause lifts within 12 hours of its time, else it fails withqueue_expired. - A suppressed address is skipped at the send and fires
email.suppressedto the endpoints that chose it. A recipient suppressed between the send and its time firesemail.failedwithrecipient_suppressedandemail.suppressed: handle one of them.email.failedfor 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 with422 recipient_suppressed: no message, no event. - Dedupe on
tawked-webhook-id, or onevent,data.idanddata.recipient.id.
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 inevents; 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:
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.completedis 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.pausedorcampaign.completedfollows. - 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, orcampaigns.settings.updatewithcampaign_message_webhooks: trueon the Account API): a campaign of 5,000 customers is about 15,000 deliveries. The statuses of every other message are unchanged.
Partner events
Theservice.* 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.
reason_code of a rejection, the subscriptions and the feed to poll instead.