One webhook covers your whole partner account. It is set in the partner console under Integration: 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.
Partner-provisioned applications have no per-application webhook. Their verification.* and message.* 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, 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) and tawked-event. 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: 5 attempts in all, right away and then after 1 minute, 5 minutes, 30 minutes and 2 hours. Answer 2xx quickly and do your own work after acknowledging, or the delivery is retried.
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.
