Webhooks Reference

Threll delivers events to your HTTPS endpoint as JSON. Async events are fire-and-forget; sync events expect a JSON response that influences the call.

Pick an event or topic from the sidebar.

Request headers

Every webhook delivery carries the following headers:

call.worker_request

Pre-call hook fired right before a call starts. Your endpoint returns the worker configuration to use for the call.

When it fires

Fires immediately before the outbound call starts (or on inbound entry) so scheduled calls re-resolve their configuration when they actually run.

Expected response

Return JSON with the worker configuration overrides to merge onto the call before the voice session starts. When data.contextCarryover is present, Threll is about to give the worker context from that earlier call: return your own context to replace it, or suppressContextCarryover to drop it.

Response fields

Example response

{
  "instructions": "You are calling Acme Corp to follow up on their demo request. Be concise and friendly.",
  "config": {
    "voiceId": "Kore",
    "firstSpeechTimeout": 2
  },
  "tools": [
    {
      "name": "lookup_account",
      "description": "Look up an account by its number.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "accountNumber": {
            "type": "string"
          }
        },
        "required": [
          "accountNumber"
        ]
      },
      "deliveryUrl": "https://example.com/threll/tools",
      "signingSecret": "whsec_your_tool_signing_secret"
    }
  ]
}

Payload fields

Example payload

{
  "type": "call.worker_request",
  "data": {
    "callId": "5f1a3e7b-2c8d-49a6-b0e4-7d9f3c5a1b2e",
    "accountId": "9c3e8f02-7a14-4b62-bc59-1d8e5fa3027b",
    "workerId": "2b7d9a4c-6e3f-48a1-9c5d-8e0b4f2a1c8d",
    "direction": "outbound",
    "customer": {
      "number": "+15555550100",
      "name": "Acme Corp"
    }
  }
}

call.tool_call

Mid-call external tool dispatch. Threll forwards a tool call from the worker to your endpoint, which returns the tool result.

When it fires

Fires every time the worker invokes an externally-registered tool (provider="external") during an active call. The voice session pauses on the response.

Expected response

Return JSON with the tool result that should be presented back to the worker.

Response fields

Example response

{
  "result": {
    "accountNumber": "12345",
    "name": "Acme Corp",
    "plan": "enterprise",
    "balanceDue": 0
  }
}

Payload fields

Example payload

{
  "type": "call.tool_call",
  "data": {
    "callId": "5f1a3e7b-2c8d-49a6-b0e4-7d9f3c5a1b2e",
    "accountId": "9c3e8f02-7a14-4b62-bc59-1d8e5fa3027b",
    "workerId": "2b7d9a4c-6e3f-48a1-9c5d-8e0b4f2a1c8d",
    "toolCallId": "c8d4e9f2-1a3b-4c7d-8e0f-9a2b3c4d5e6f",
    "name": "lookup_account",
    "arguments": {
      "accountNumber": "12345"
    }
  }
}

call.transcript

A transcript turn (final or interim depending on the worker config) recorded during the call.

When it fires

Streamed as transcript turns are committed. Fire-and-forget delivery; no response expected.

Payload fields

Example payload

{
  "type": "call.transcript",
  "data": {
    "callId": "5f1a3e7b-2c8d-49a6-b0e4-7d9f3c5a1b2e",
    "turnIndex": 0,
    "role": "user",
    "text": "Hi, I have a question about your enterprise plan.",
    "isFinal": true,
    "confidence": 0.92,
    "source": "whisper-nb",
    "ts": "2026-06-08T10:00:15Z"
  }
}

call.status_update

Lifecycle status change for the call (ringing, in_progress, etc.).

When it fires

Fires whenever the call status changes during its lifecycle. Fire-and-forget.

Payload fields

Example payload

{
  "type": "call.status_update",
  "data": {
    "callId": "5f1a3e7b-2c8d-49a6-b0e4-7d9f3c5a1b2e",
    "status": "in_progress",
    "providerStatus": "ringing",
    "ts": "2026-06-08T10:00:15Z"
  }
}

call.ended

Final event for the call, delivered exactly once. Once you receive this, no further events for the call will be delivered. When status is "failed", failedReason names the cause (see Failure reasons).

When it fires

Fires once a dialed call reaches a terminal status: completed, voicemail, no_answer, busy, canceled or failed. For a call that was answered and recorded, it fires after post-processing, so transcript and nextAction are populated. For a call that never connected — voicemail, no answer, a failed dial — there is nothing to analyse, so those fields are omitted and only the call metadata is present. A scheduled call that is canceled before dialing starts does not emit this event; track those via its status instead.

Payload fields

Example payload

{
  "type": "call.ended",
  "data": {
    "callId": "5f1a3e7b-2c8d-49a6-b0e4-7d9f3c5a1b2e",
    "status": "completed",
    "failedReason": null,
    "accountId": "9c3e8f02-7a14-4b62-bc59-1d8e5fa3027b",
    "workerId": "2b7d9a4c-6e3f-48a1-9c5d-8e0b4f2a1c8d",
    "direction": "outbound",
    "fromNumber": "+15555550111",
    "toNumber": "+15555550100",
    "duration": 96,
    "startedAt": "2026-06-08T10:00:00Z",
    "endedAt": "2026-06-08T10:01:36Z",
    "recordingAvailable": true,
    "recording": {
      "url": "https://api.threll.io/recordings/5f1a3e7b-2c8d-49a6-b0e4-7d9f3c5a1b2e?sub=7c1d2e3f-4a5b-46c7-8d9e-0f1a2b3c4d5e&exp=1781517696&sig=4f2a…",
      "urlExpiresAt": "2026-06-15T10:01:36Z",
      "contentType": "audio/wav"
    },
    "callScript": {
      "source": "documents",
      "contentHash": "sha256:9b1f0c4e7a2d5b8c3e6f9a0d1c4b7e2a5d8f1c3b6e9a2d4f7c0b3e5a8d1f4c6b",
      "documents": [
        {
          "documentId": "e4f5a6b7-8c9d-40e1-a2b3-c4d5e6f7a8b9",
          "title": "Appointment reminder",
          "contentHash": "sha256:3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b"
        }
      ]
    },
    "personId": "b2c3d4e5-6f7a-48b9-0c1d-2e3f4a5b6c7d"
  }
}

Failure reasons

When a call ends with status failed, thecall.ended payload carriesdata.failedReason. It is absent when the call failed at the carrier without a reason Threll could classify.

Signature verification

Every delivery is signed with the subscription's signing secret usingHMAC-SHA256 over the raw request body. Compare the hex digest to the X-Threll-Signature header using a constant-time comparison.

echo -n "$RAW_REQUEST_BODY" | \
  openssl dgst -sha256 -hmac "whsec_..." | \
  awk '{print $2}'

Delivery & retries

Async events are delivered fire-and-forget via the event bus; sync events are delivered inline and the response is fed back into the call.

• Sync deliveries time out after a few seconds. Return JSON quickly; on error or timeout, the call proceeds with defaults (unless the subscription is marked required).
• Async deliveries are retried with exponential backoff on non-2xx responses.
• Every delivery has a unique X-Threll-Event-Id; treat handlers as idempotent.

Testing

Use the subscription Test action in Settings → Developer (or POST /v1/accounts/{accountId}/webhook-subscriptions/{id}/test) to dispatch a synthetic event matching the subscription's event type.