Webhooks

Webhooks deliver signed call lifecycle events to a URL you configure. There's no REST endpoint to create or manage one — that's a dashboard-only surface, covered in Webhooks — Guide. This page covers the wire format: what a delivery looks like and how to verify it.

Event envelope

Inbound events use this shape:

{
  "id": "uuid",
  "type": "call.ended",
  "created_at": "2026-07-03T12:00:00Z",
  "api_version": "v1",
  "data": {},
  "request_id": "uuid"
}

Event types

• call.started, call.ended, call.failed, call.transcript.updated
• tool.call.requested, tool.call.completed
• agent.handoff.requested, call.transfer.updated
• webhook.test (from test endpoint)

Signature header

X-Taliiq-Signature: t=<unix_timestamp>,v1=<hmac_sha256_hex>

Compute HMAC-SHA256 over {timestamp}.{raw_json_body} using your webhook secret. Reject events older than 5 minutes.

Delivery uses X-Taliiq-Event-Id for idempotent replay handling and retries transport/5xx/429 failures with exponential backoff. Endpoint URLs must be public HTTPS addresses; private hosts and HTTP redirects are rejected.

Delivery history is available via Webhook delivery logs.

Auto-disable after repeated failures

An endpoint that fails delivery 5 times in a row for a single event (retries exhausted) and has accumulated 10 or more consecutive failed deliveries overall is automatically set to is_active: false — no further events are sent to it until you re-enable it. An in-app notification is sent to your organization the moment this happens, so a broken integration doesn't go unnoticed. Re-enable it from Manage → Webhooks once your endpoint is fixed — this also resets the failure counter.