Skip to main content
One webhook covers your whole partner account. The owner, or whoever manages the clients, sets it in the console under Clients → API and webhook, Webhook: an HTTPS URL and a signing secret, revealed on demand and rotatable there and nowhere else. Which events reach it is a subscription you choose in the console or with PUT /v1/partner/webhook; the catalogue, the defaults and the opt-in events are on the Events page, together with the feed you can poll instead of running a webhook at all. Client applications have no per-application webhook. Their verification.* events reach your partner webhook instead, with your external_id in the data, once you opt in.

​
Reading the configuration

GET /v1/partner/webhook answers the URL, whether a secret exists, the low-balance threshold, the events that reach the URL, the default set and every event you may subscribe to. The secret is never returned. PUT /v1/partner/webhook takes events and low_balance_threshold_halalas; a body naming url or secret is refused with a message pointing at the console.

​
The envelope

The same envelope as every Tawked webhook:
Two more, as they arrive:

​
Deliveries

GET /v1/partner/webhook/deliveries is the Delivery log the console shows under Clients → API and webhook, newest first: every webhook call with its status (pending, delivered, failed), the attempts so far, the last response code or error, and the next attempt when one is scheduled. Filter by status and event, page with cursor. POST /v1/partner/webhook/deliveries/{id}/retry gives a failed delivery one more attempt, to the URL configured now and with a fresh signature; anything but failed answers 409 not_retryable with the current status.

​
Signature and retries

Every delivery carries tawked-timestamp (milliseconds since the epoch, the same value as sent_at), tawked-signature (hex HMAC-SHA256 of "{timestamp}.{raw body}" with your secret), tawked-event and tawked-webhook-id (the event’s id, the same on every retry and on a delivery retried by hand). Compute the HMAC over the raw request body before parsing it, compare in constant time, and reject timestamps older than a few minutes. The code on the Webhooks page works unchanged with your partner secret. Delivery retries on anything but a 2xx within 5 seconds: 5 attempts in all, right away and then after 1 minute, 5 minutes, 30 minutes and 2 hours, each wait counted from the attempt before it. A timeout, a failed connection and a redirect count as failures too. Answer 2xx quickly and do your own work after acknowledging, or the delivery is retried. After the fifth failure the delivery is failed until you retry it. Deliveries are not ordered and can repeat, so make your handler idempotent on the tawked-webhook-id header (or on event together with the ids in data), and compare states rather than trusting arrival order. Webhooks has the schedule as a table.
balance.low fires once per crossing: on the charge whose before and after straddle your threshold, and again only after a top-up lifts the balance back above it. A threshold of 0 turns the alert off. Keep it high enough for a top-up to land before the balance reaches zero, since a send with an empty balance answers 402 insufficient_credits.
Last modified on October 20, 2026