Trillet AI logo

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

MethodPathScope
POST/partner/v1/webhook-endpointswebhooks:write
GET/partner/v1/webhook-endpointsevents: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-secretwebhooks:write
POST/partner/v1/webhook-endpoints/{id}/testwebhooks:write
GET/partner/v1/eventsevents:read
GET/partner/v1/events/{eventId}events:read
POST/partner/v1/events/{eventId}/redeliverwebhooks:write
GET/partner/v1/tenants/{tenantId}/calls/{callId}/recordingresources: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"]
  }'
urlstringrequired

A public https URL on the default port 443. No credentials or fragment in the URL.

descriptionstring

Up to 200 characters.

enabledEventsstring[]

Event types to send, or ["*"] for all (the default). Up to 50 entries.

includeConversationDataboolean | 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.

redactPIIboolean

Mask 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" }
      ]
    }
  }
}
FieldNotes
idEvent ID. Also sent in the webhook-id header. Use it to de-duplicate.
typeThe event type
createdWhen the event happened, in Unix seconds
livemodeAlways true until sandbox tenants are available
tenantThe tenant's id and externalId. null for account-level events.
dataDepends 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:

TypeWhendata
call.startedA call is connected to an agent and its call record is activecall, direction, callType
call.transferredA transfer to a person or another number connectedcall, team, target, mode
call.transfer_failedA transfer attempt failed. Sent once per attempt.call, team, target, mode, reason
tool.failedA 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.blockedA call was refused before reaching the agent: the tenant is suspended, an inbound calling rule matched, or there is not enough balancecall, reason, rule, direction (inbound or outbound/webcall)

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

TypeWhendata
call.endedA call ended normallycall
call.no_answerAn outbound call was not answered, was busy, or reached voicemailcall
call.failedA call failedcall
call.blockedA call record finished with status blockedcall
call.analyzedThe call has a summary or extracted datacall
booking.created, booking.rescheduled, booking.cancelledThe call created, moved or cancelled an appointmentcall
recording.availableThe call has a recordingcall

Other events:

TypeWhendata
workflow_run.completed, workflow_run.failedA workflow run finishederror (failed runs only). The payload does not include the workflow ID or run ID.
number.provisionedA number was bought or registeredphoneNumber, provider
number.releasedA number was released, either directly or because its tenant was deletedphoneNumber. A direct release also has provider (currently null); a tenant delete has reason: "tenant_deleted" instead.
number.renewal_failedA monthly number charge failedphoneNumber, amount
tenant.createdA tenant was createdexternalId
tenant.updatedA tenant's name, metadata or spend cap changednone
tenant.suspendedA tenant was suspendedreason, if given
tenant.resumed, tenant.deleted, tenant.restoredTenant lifecyclenone
usage.threshold_reachedA spend cap reached 80% or 100% this month. See Spend caps.scope, percent, cap, monthToDate, month
endpoint.testYou sent a test eventmessage

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:

TypeWhen
sms.received, sms.sent, sms.failedText 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: 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:

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.

// 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 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.

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