Skip to main content

​
Concept

Timely.ai Webhooks are HTTP POST notifications automatically sent to the URL you configure whenever a relevant event occurs in the workspace — a message received, a conversation closed, a contact created, a channel disconnected, and more. Instead of polling the API periodically to check whether something changed, you receive the data as soon as the event occurs. Each webhook has a secret generated at creation time, used to sign deliveries with HMAC-SHA256 in the X-Timely-Signature header. This ensures only Timely.ai can send events to your endpoint. To understand how to validate the signature and implement a webhook receiver, see the webhooks overview.

​
Webhook Lifecycle

create webhook (URL + events + generated secret)
    │
    ▼
active → Timely delivers events to the URL
    │
    ├── event occurs → delivery (success or failure)
    │       │
    │       └── failure → retry with exponential backoff
    │
    ├── test → synthetic event delivery
    │
    ├── query deliveries → delivery history
    │
    └── delete → stops receiving events
After 5 consecutive failures, the webhook is marked as failing but remains active. New events continue to be queued — you receive an email alert and can act before losing data.

​
Main Fields

FieldTypeDescription
idstring (UUID)Unique webhook ID
urlstringDelivery destination URL (must be HTTPS)
eventsarrayList of subscribed event categories
statusenumactive | inactive | failing
descriptionstringInternal description of the webhook’s purpose
secretstringHMAC secret — shown only at creation (write-once)
created_atstringISO 8601 creation timestamp
last_delivery_atstringISO 8601 last delivery attempt timestamp
success_ratenumberSuccess rate of last 100 deliveries (0–1)

​
Delivery Fields

FieldTypeDescription
idstring (UUID)Delivery ID
webhook_idstring (UUID)Webhook that generated the delivery
event_typestringType of event delivered
statusenumsuccess | failed | pending
http_statusnumberHTTP status code returned by your server
attemptnumberAttempt number (1 = first)
response_time_msnumberResponse time in milliseconds
delivered_atstringISO 8601 attempt timestamp

​
Available Event Categories

CategoryEvents
conversation.*created, closed, reopened, assigned
message.*received, sent, delivered, read, failed
contact.*created, updated, deleted
agent.*handoff_started, handoff_completed, transferred
channel.*connected, disconnected, error
credit.*low, depleted
plan.*changed

​
Available Endpoints

See the left sidebar for the full list of endpoints in this group. Each endpoint has its own page with request/response schema, cURL/JS/Python examples, and an interactive playground.

​
Next Steps

Webhooks overview

Understand how to validate signatures and implement a receiver.

Your first request

If you haven’t made your first call yet, start here.