Events and webhooks
Trillet OEM signed webhooks for what happens across your tenants, with retries, an event log and redelivery.
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.
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 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, because an endpoint receives events for every tenant.
Add an endpoint
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"]
}'
urlstringrequiredA public https URL on the default port 443. No credentials or fragment in the URL.
descriptionstringUp to 200 characters.
enabledEventsstring[]Event types to send, or ["*"] for all (the default). Up to 50 entries.
includeConversationDataboolean | nullWhether 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.
redactPIIbooleanMask emails, phone numbers and card-like numbers in conversation data. Default false.
The response is 201 with the endpoint plus its signing secret (whsec_...). The secret is returned only here and on rotation, so store it.
{
"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
{
"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. 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. | scope, percent, cap, monthToDate, month |
endpoint.test | You sent a test event | message |
Notes on the in-call events:
data.callis the call record at delivery time. It can benull, for example for a call refused for insufficient balance, which has no call record.targetis masked: only the last 4 digits of a phone number or SIP user are shown.tool.faileddoes not forward the third-party response body.erroris a short error message of up to 300 characters.kindiscustom_toolorapiwhen known.reasononcall.blockedis a short code such asworkspace_suspended,insufficient_balanceorinbound_rule.ruleis the name of the matched inbound rule, when there is one.call.blockedis 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 ondata.call.idas well as the eventid.
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. 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: falseon an endpoint to leave them out. Call metadata (numbers, times, duration, status, cost, recording link) is still sent. - Set
redactPII: trueto 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-levelfromandtonumbers 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:
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 asidin the bodywebhook-timestamp: when this delivery attempt was signed, in Unix secondswebhook-signature:v1,<base64 HMAC-SHA256>of{webhook-id}.{webhook-timestamp}.{raw body}, keyed with the base64-decoded part of your secret afterwhsec_. 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.
// 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
});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
2xxwithin 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
idand usecreatedfor 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.
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:
{
"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:
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.
Last updated on