---
title: "Events and webhooks"
sidebarTitle: "Events and webhooks"
description: "Trillet OEM signed webhooks for what happens across your tenants, with retries, an event log and redelivery."
lastUpdated: "2026-11-04"
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://trillet-ai.jamdesk.app/llms.txt). Append `.md` to any page URL for its markdown version.

<Note>
  **Early access.** Trillet OEM is built and in testing with design partners. Contact your account manager to have it enabled for your account. Details may still change.
</Note>

Register webhook endpoints on your partner account. Each endpoint receives the event types it subscribes to, from all of your tenants, signed with the [Standard Webhooks](https://www.standardwebhooks.com) format so you can verify they came from Trillet.

## Endpoints

| Method | Path | Scope |
|---|---|---|
| `POST` | `/partner/v1/webhook-endpoints` | `webhooks:write` |
| `GET` | `/partner/v1/webhook-endpoints` | `events:read` |
| `GET` | `/partner/v1/webhook-endpoints/{id}` | `events:read` |
| `PATCH` | `/partner/v1/webhook-endpoints/{id}` | `webhooks:write` |
| `DELETE` | `/partner/v1/webhook-endpoints/{id}` | `webhooks:write` |
| `POST` | `/partner/v1/webhook-endpoints/{id}/rotate-secret` | `webhooks:write` |
| `POST` | `/partner/v1/webhook-endpoints/{id}/test` | `webhooks:write` |
| `GET` | `/partner/v1/events` | `events:read` |
| `GET` | `/partner/v1/events/{eventId}` | `events:read` |
| `POST` | `/partner/v1/events/{eventId}/redeliver` | `webhooks:write` |
| `GET` | `/partner/v1/tenants/{tenantId}/calls/{callId}/recording` | `resources:read` |

Webhook endpoint routes need a key that is not [restricted to some tenants](https://trillet-ai.jamdesk.app/voice-engine/authentication#restricting-a-key-to-some-tenants), because an endpoint receives events for every tenant.

## Add an endpoint

```bash
curl -X POST https://api.trillet.ai/partner/v1/webhook-endpoints \
  -H "Authorization: Bearer tpk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/trillet/events",
    "description": "Production",
    "enabledEvents": ["call.ended", "call.analyzed", "booking.created"]
  }'
```

<ParamField body="url" type="string" required>
  A public `https` URL on the default port 443. No credentials or fragment in the URL.
</ParamField>
<ParamField body="description" type="string">
  Up to 200 characters.
</ParamField>
<ParamField body="enabledEvents" type="string[]">
  Event types to send, or `["*"]` for all (the default). Up to 50 entries.
</ParamField>
<ParamField body="includeConversationData" type="boolean | null">
  Whether call payloads include the summary, extracted data, variables, booking and transcript. `null` (the default) uses your account setting, which is on unless Trillet has turned it off for you.
</ParamField>
<ParamField body="redactPII" type="boolean">
  Mask emails, phone numbers and card-like numbers in conversation data. Default `false`.
</ParamField>

The response is `201` with the endpoint plus its signing `secret` (`whsec_...`). The secret is returned only here and on rotation, so store it.

```json
{
  "object": "webhook_endpoint",
  "id": "e4e4e4e4e4e4e4e4e4e4e4e4",
  "url": "https://api.example.com/trillet/events",
  "description": "Production",
  "enabledEvents": ["call.ended", "call.analyzed", "booking.created"],
  "status": "enabled",
  "disabledReason": null,
  "failingSince": null,
  "includeConversationData": null,
  "redactPII": false,
  "createdAt": "2026-11-02T10:30:00.000Z",
  "secret": "whsec_..."
}
```

An account can have up to 10 endpoints (`409` `too_many_endpoints`). An invalid URL returns `400` `invalid_url`, and an unknown event type `400` `invalid_events`. An endpoint ID that is not yours returns `404` `endpoint_not_found`. `DELETE` returns `{ "object": "webhook_endpoint", "id": "...", "deleted": true }`.

`PATCH` accepts the same fields plus `status` (`enabled` or `disabled`). Setting `status: "enabled"` re-enables an endpoint that was disabled after failing.

`POST /webhook-endpoints/{id}/test` sends an `endpoint.test` event to that endpoint only and returns `202` with the event ID. The endpoint must be enabled (`409` `endpoint_disabled` otherwise) and subscribed to `endpoint.test` or `*` (`409` `endpoint_not_subscribed` otherwise).

## Event shape

```json
{
  "id": "evt_e6e6e6e6e6e6e6e6e6e6e6e6",
  "type": "call.ended",
  "created": 1762095851,
  "livemode": true,
  "tenant": { "id": "d9d9d9d9d9d9d9d9d9d9d9d9", "externalId": "cust_8842" },
  "data": {
    "call": {
      "id": "e5e5e5e5e5e5e5e5e5e5e5e5",
      "direction": "inbound",
      "channel": "phone",
      "status": "completed",
      "from": "+15125550177",
      "to": "+15125550142",
      "agentId": "e0e0e0e0e0e0e0e0e0e0e0e0",
      "callFlowId": "e1e1e1e1e1e1e1e1e1e1e1e1",
      "startedAt": "2026-11-02T15:01:40.000Z",
      "endedAt": "2026-11-02T15:04:11.000Z",
      "durationSeconds": 151,
      "endReason": "user_hangup",
      "endedBy": "user",
      "cost": 0.38,
      "batchId": null,
      "recording": {
        "available": true,
        "url": "https://api.trillet.ai/partner/v1/tenants/d9d9d9d9d9d9d9d9d9d9d9d9/calls/e5e5e5e5e5e5e5e5e5e5e5e5/recording"
      },
      "summary": "Caller booked a cleaning for Thursday 3pm.",
      "extractedData": { "appointment_type": "cleaning" },
      "variables": { "customer_name": "Sam" },
      "booking": { "booked": true },
      "transcript": [
        { "role": "assistant", "text": "Harbour Dental, how can I help?", "at": "2026-11-02T15:01:41.000Z" }
      ]
    }
  }
}
```

| Field | Notes |
|---|---|
| `id` | Event ID. Also sent in the `webhook-id` header. Use it to de-duplicate. |
| `type` | The event type |
| `created` | When the event happened, in Unix seconds |
| `livemode` | Always `true` until sandbox tenants are available |
| `tenant` | The tenant's `id` and `externalId`. `null` for account-level events. |
| `data` | Depends on the type. Call events carry `data.call`. |

Call payloads are built when each delivery is sent, from the tenant's region, so a redelivery shows the call record as it is at that time. `data.call.id` is the call history ID: use it with `GET /v2/api/call-history/{callHistoryId}`, `GET /v2/api/recordings/{callHistoryId}` and to match `callHistoryId` in [per-call usage](https://trillet-ai.jamdesk.app/voice-engine/usage-and-billing#per-call). Values in `data.call` can be `null` when the call did not record them. `direction` is `inbound`, `outbound` or `web`; `channel` is `phone`, `whatsapp` or `web`; `status` is `completed`, `pending`, `failed` or `blocked`. `endReason` and `endedBy` are descriptive text, not a fixed list. `cost` is the call charge in USD. The conversation fields (`summary`, `extractedData`, `variables`, `booking`, `transcript`) are omitted when conversation data is off for the endpoint.

## Event types

### Sent today

Events sent during a call, as it happens:

| Type | When | `data` |
|---|---|---|
| `call.started` | A call is connected to an agent and its call record is active | `call`, `direction`, `callType` |
| `call.transferred` | A transfer to a person or another number connected | `call`, `team`, `target`, `mode` |
| `call.transfer_failed` | A transfer attempt failed. Sent once per attempt. | `call`, `team`, `target`, `mode`, `reason` |
| `tool.failed` | A custom tool or API call during a call failed or returned an HTTP error. At most 5 per call. | `call`, `tool`, `kind`, `status` (HTTP status, when there is one), `error` |
| `call.blocked` | A call was refused before reaching the agent: the tenant is suspended, an inbound calling rule matched, or there is not enough balance | `call`, `reason`, `rule`, `direction` (`inbound` or `outbound/webcall`) |

Events sent after a call's post-call processing finishes, not at the moment it ends:

| Type | When | `data` |
|---|---|---|
| `call.ended` | A call ended normally | `call` |
| `call.no_answer` | An outbound call was not answered, was busy, or reached voicemail | `call` |
| `call.failed` | A call failed | `call` |
| `call.blocked` | A call record finished with status `blocked` | `call` |
| `call.analyzed` | The call has a summary or extracted data | `call` |
| `booking.created`, `booking.rescheduled`, `booking.cancelled` | The call created, moved or cancelled an appointment | `call` |
| `recording.available` | The call has a recording | `call` |

Other events:

| Type | When | `data` |
|---|---|---|
| `workflow_run.completed`, `workflow_run.failed` | A workflow run finished | `error` (failed runs only). The payload does not include the workflow ID or run ID. |
| `number.provisioned` | A number was bought or registered | `phoneNumber`, `provider` |
| `number.released` | A number was released, either directly or because its tenant was deleted | `phoneNumber`. A direct release also has `provider` (currently `null`); a tenant delete has `reason: "tenant_deleted"` instead. |
| `number.renewal_failed` | A monthly number charge failed | `phoneNumber`, `amount` |
| `tenant.created` | A tenant was created | `externalId` |
| `tenant.updated` | A tenant's name, metadata or spend cap changed | none |
| `tenant.suspended` | A tenant was suspended | `reason`, if given |
| `tenant.resumed`, `tenant.deleted`, `tenant.restored` | Tenant lifecycle | none |
| `usage.threshold_reached` | A spend cap reached 80% or 100% this month. See [Spend caps](https://trillet-ai.jamdesk.app/voice-engine/usage-and-billing#spend-caps). | `scope`, `percent`, `cap`, `monthToDate`, `month` |
| `endpoint.test` | You sent a test event | `message` |

Notes on the in-call events:

- `data.call` is the call record at delivery time. It can be `null`, for example for a call refused for insufficient balance, which has no call record.
- `target` is masked: only the last 4 digits of a phone number or SIP user are shown.
- `tool.failed` does not forward the third-party response body. `error` is a short error message of up to 300 characters. `kind` is `custom_tool` or `api` when known.
- `reason` on `call.blocked` is a short code such as `workspace_suspended`, `insufficient_balance` or `inbound_rule`. `rule` is the name of the matched inbound rule, when there is one.
- `call.blocked` is listed in both tables: one is sent at the moment of refusal, the other when a blocked call record finishes post-call processing. The same call can produce both, so de-duplicate on `data.call.id` as well as the event `id`.

### Coming soon

These types are accepted in `enabledEvents` but are not sent yet:

| Type | When |
|---|---|
| `sms.received`, `sms.sent`, `sms.failed` | Text messages |

Template rollout events are planned with [templates](https://trillet-ai.jamdesk.app/voice-engine/templates). New event types may be added at any time. Ignore types you do not handle.

## Conversation data

Transcripts, summaries, extracted data, dynamic variables and booking details are included in call payloads by default.

- Set `includeConversationData: false` on an endpoint to leave them out. Call metadata (numbers, times, duration, status, cost, recording link) is still sent.
- Set `redactPII: true` to keep them but mask email addresses as `[email]`, phone numbers as `[phone]` and card-like numbers as `[number]` in the summary, extracted data, variables and transcript. Masking is pattern based and best effort. IDs, times and URLs are not masked. The top-level `from` and `to` numbers are not masked.

## Recordings

Recordings are never included in a payload. When a call has one, `data.call.recording.url` points at the recording download endpoint. Fetch it with a partner key that has `resources:read`:

```bash
curl -L -o call.mp3 \
  "https://api.trillet.ai/partner/v1/tenants/d9d9d9d9d9d9d9d9d9d9d9d9/calls/e5e5e5e5e5e5e5e5e5e5e5e5/recording" \
  -H "Authorization: Bearer tpk_live_..."
```

The response is the audio file. A call with no recording returns `404` `recording_not_found`.

## Verifying signatures

Each delivery is a `POST` with a JSON body and three headers:

- `webhook-id`: the event ID, the same as `id` in the body
- `webhook-timestamp`: when this delivery attempt was signed, in Unix seconds
- `webhook-signature`: `v1,<base64 HMAC-SHA256>` of `{webhook-id}.{webhook-timestamp}.{raw body}`, keyed with the base64-decoded part of your secret after `whsec_`. During a secret rotation there are two signatures, separated by a space.

Any Standard Webhooks library verifies this for you. Verify against the raw request body, before any JSON parsing, and reject timestamps more than 5 minutes old.

### Node.js

```js
// npm install standardwebhooks express
import express from 'express';
import { Webhook } from 'standardwebhooks';

const app = express();
const wh = new Webhook(process.env.TRILLET_WEBHOOK_SECRET); // whsec_...

app.post('/trillet/events', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    event = wh.verify(req.body.toString('utf8'), {
      'webhook-id': req.header('webhook-id'),
      'webhook-timestamp': req.header('webhook-timestamp'),
      'webhook-signature': req.header('webhook-signature'),
    });
  } catch {
    return res.status(400).send('invalid signature');
  }
  res.sendStatus(204); // respond first, then do the work
  handle(event); // de-duplicate on event.id
});
```

### Python

```python
# pip install standardwebhooks flask
import os
from flask import Flask, request
from standardwebhooks.webhooks import Webhook

app = Flask(__name__)
wh = Webhook(os.environ["TRILLET_WEBHOOK_SECRET"])  # whsec_...

@app.post("/trillet/events")
def events():
    try:
        event = wh.verify(request.get_data(), {
            "webhook-id": request.headers["webhook-id"],
            "webhook-timestamp": request.headers["webhook-timestamp"],
            "webhook-signature": request.headers["webhook-signature"],
        })
    except Exception:
        return "invalid signature", 400
    handle(event)  # de-duplicate on event["id"]; queue slow work
    return "", 204
```

### Node.js (no library)

```js
import crypto from 'node:crypto';

export function verifyTrilletEvent(rawBody, headers, secret) {
  const id = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  const signatures = headers['webhook-signature'] || '';

  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const expected = crypto
    .createHmac('sha256', key)
    .update(`${id}.${timestamp}.${rawBody}`)
    .digest('base64');

  return signatures.split(' ').some((entry) => {
    const [version, signature] = entry.split(',');
    return (
      version === 'v1' &&
      signature.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
    );
  });
}
```

### Rotating a secret

`POST /webhook-endpoints/{id}/rotate-secret` returns a new `secret`. The previous secret keeps signing alongside the new one for 24 hours (`previousSecretExpiresAt`), so you can deploy the new secret without missing events.

## Delivery and retries

- Respond with any `2xx` within 10 seconds. Do slow work after responding. Redirects are not followed.
- A failed delivery is retried up to 9 times, after 10 seconds, 1 minute, 5 minutes, 30 minutes, 1 hour, 2 hours, 4 hours, 6 hours and 8 hours: about 22 hours in all.
- Events can arrive more than once and out of order. De-duplicate on `id` and use `created` for ordering.
- An endpoint that keeps failing for 3 days is disabled, and the owner of your partner account is emailed. Events raised while it is disabled are still recorded in the event log. Fix the endpoint, re-enable it with `PATCH`, then redeliver what you missed.

## Event log and redelivery

The event log keeps events for 30 days. It records an event when at least one of your endpoints subscribes to its type.

```bash
curl "https://api.trillet.ai/partner/v1/events?type=call.ended&tenantId=d9d9d9d9d9d9d9d9d9d9d9d9&since=1762041600&limit=50" \
  -H "Authorization: Bearer tpk_live_..."
```

`GET /events` accepts `type`, `tenantId`, `since` (Unix seconds), `limit` and `starting_after`. Each entry shows the delivery status per endpoint:

```json
{
  "object": "event",
  "id": "evt_e6e6e6e6e6e6e6e6e6e6e6e6",
  "type": "call.ended",
  "tenantId": "d9d9d9d9d9d9d9d9d9d9d9d9",
  "data": {},
  "created": 1762095851,
  "deliveries": [
    {
      "endpointId": "e4e4e4e4e4e4e4e4e4e4e4e4",
      "status": "failed",
      "attempts": 10,
      "lastAttemptAt": "2026-11-03T13:05:00.000Z",
      "lastStatusCode": 503,
      "lastError": "HTTP 503"
    }
  ]
}
```

In the list, `data` holds only the facts stored with the event. `GET /events/{eventId}` returns one event and, for call events, renders `data.call` as a delivery would, using your account's conversation data setting. It does not apply an endpoint's `redactPII`. An unknown event ID returns `404` `event_not_found`.

To send an event again:

```bash
curl -X POST https://api.trillet.ai/partner/v1/events/evt_e6e6e6e6e6e6e6e6e6e6e6e6/redeliver \
  -H "Authorization: Bearer tpk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "endpointId": "e4e4e4e4e4e4e4e4e4e4e4e4" }'
```

With `endpointId`, the event is sent to that endpoint even if it is not subscribed to the event's type. Without `endpointId`, the event is sent to every enabled endpoint subscribed to its type. Returns `202` with the number of endpoints it is being sent to. With no enabled endpoint to send to, it returns `409` `no_enabled_endpoint`. Redelivery needs `webhooks:write`. Unlike managing endpoints, it also works with a key restricted to some tenants, for those tenants' events.
