Webhooks¶
Kothok sends each event to your system as one signed JSON POST: leads,
conversations, tickets, meetings and, for shops, orders.
Set it up¶
Owners and admins do this under Settings → API and webhooks:
- Select Set up webhook and paste the Endpoint URL. It must be public
https://. Zapier, Make and Google Apps Script URLs work. - Optionally add an auth header.
- Pick the Events to send. Shops also pick the order details to include.
- Save, then copy the signing secret (
whsec_…). - Select Send test event to check your endpoint.
One business has one webhook; tell events apart by X-Kothok-Event.
The request¶
POST https://your-system.example.com/kothok/events
Content-Type: application/json
User-Agent: Kothok-Webhooks/1.0
X-Kothok-Event: lead.created
X-Kothok-Delivery: 3f1c2b9e-8d4a-5e6f-9a1b-2c3d4e5f6a7b
X-Kothok-Timestamp: 1791641113
X-Kothok-Signature: sha256=5d41402abc4b2a76b9719d911017c592...
| Header | Value |
|---|---|
X-Kothok-Event |
Event name, e.g. lead.created |
X-Kothok-Delivery |
Delivery ID. The same on every retry and resend. |
X-Kothok-Timestamp |
Unix seconds when this attempt was signed |
X-Kothok-Signature |
sha256=<hex>. See Verify signatures. |
| Your auth header | Only if you set one |
Every body has the same envelope. The record sits under lead, conversation,
ticket, meeting or order.
| Field | Description |
|---|---|
event |
Event name |
id |
Delivery ID. Use it to skip repeats. |
created_at |
When the event was sent (ISO 8601, UTC) |
test |
true on test events only |
changes |
Update events only. See Events. |
source, request |
order.updated only. See Order API. |
The record is the full object at send time, not a diff. Answer 2xx within 10
seconds; redirects aren't followed and the body is ignored. Failed sends are
retried.
Auth header¶
Optional, for endpoints that need a fixed key, e.g. Authorization: Bearer your-key.
Requests are signed either way. The name is up to 64 characters and can't be a
standard header or X-Kothok-*; the value is up to 2,000 characters and write-only.
Test events and the log¶
Send test event sends a sample with "test": true (orders use KO-TEST01).
Recent deliveries shows the last 50 sends from the past 30 days with the body,
your response and the time taken; bodies over 16 KB aren't kept. Events that happen
while Send events is off are never sent.