Platform
Webhooks and events
Trovacast POSTs a signed JSON event to your HTTPS endpoints when something happens. Events are retried for about three days and kept for 30.
Register an endpoint and choose its events: messages sent, delivered, read, failed and received; consent changes, including STOP; template reviews; WhatsApp account changes; conversations opened and resolved; calls queued, ringing, answered and ended, and their recordings. Each event's data embeds the same resource shape the matching /v1 read returns, so you parse one object whether you polled or were told.
Register an endpoint
curl -X POST 'https://api.trovacast.com/v1/webhook-endpoints' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: webhook-orders-v1' \
-H 'Content-Type: application/json' \
-d '{
"url": "https://apps.example.com/trovacast/webhook",
"events": [
"message.delivered",
"message.failed",
"message.received"
],
"description": "Order notifications"
}'{
"object": "webhook_endpoint",
"id": "ENDPOINT_ID",
"url": "https://apps.example.com/trovacast/webhook",
"description": "Order notifications",
"events": [
"message.delivered",
"message.failed",
"message.received"
],
"status": "enabled",
"secret": "whsec_AbCdEfGhIjKlMnOpQrStUvWxYz012345",
"secretLast4": "2345",
"previousSecretExpiresAt": null,
"failingSince": null,
"lastSuccessAt": null,
"lastFailureAt": null,
"createdAt": "2026-11-05T10:00:00.000Z",
"updatedAt": "2026-11-05T10:00:00.000Z"
}- URL:
https://, on a public host, at most 2,048 characters, no user name or password. Private, loopback and other non-public addresses are refused, and every address is checked again on each delivery. Redirects are never followed. - Ports: 443, 80, or any port from 1024 up except those of well-known non-HTTP services (databases, caches, queues, remote desktop); else
400WEBHOOK_URL_INVALIDwithreason: "PORT_NOT_ALLOWED". - Events: at least one. The key needs each event's read scope (the catalog's last column) to subscribe to it, and to change the URL of an endpoint that carries it.
- At most 10 endpoints per project, and at most 20 URLs set an hour (a create, or a new URL on an endpoint).
- The secret (
whsec_…) is returned by create and rotate-secret only. Store it then.
What a delivery looks like
POST /trovacast/webhook HTTP/1.1
Content-Type: application/json
User-Agent: Trovacast-Webhooks/1
Trovacast-Event-Id: 7d9b…
Trovacast-Event-Type: message.sent
Trovacast-Signature: t=1759750000,v1=4bcf66db…
{"object":"event","id":"7d9b…","type":"message.sent","livemode":true,"apiVersion":"v1","createdAt":"2026-10-06T10:00:00.000Z","organizationId":"…","data":{"message":{…}}}- Success is any
2xxwithin 10 seconds. Anything else — another status (a3xxtoo), a timeout, a refused connection — is a failure. Answer fast and do the work afterwards. - At least once: deduplicate on the envelope
id(alsoTrovacast-Event-Id), which is the same on every attempt and resend. - Order is not guaranteed. Statuses can arrive out of order, and a later one without an earlier one (
readwithoutdelivered): treat each as "now at least this far" and readmessage.status. - An event is a snapshot of the resource when it happened, written in the same transaction as the change — never for a change that rolled back.
Verify the signature
Trovacast-Signature: t=<unix seconds>,v1=<hex>, where v1 is the hex HMAC-SHA256 of <t>.<raw request body> keyed with your whole whsec_… secret. Verify before parsing JSON — a re-serialised body will not match.
- Read the raw body.
- Split the header on
,; taketand everyv1. - Reject if
|now − t|is more than 300 seconds (the replay window). - Compute the HMAC with each secret you hold and compare it, in constant time, with every
v1. Accept if any matches.
import express from 'express';
import { constructWebhookEvent } from '@trovacast/sdk/webhooks';
const app = express();
app.post('/trovacast/webhook', express.raw({ type: 'application/json' }), (req, res) => {
let event;
try {
event = constructWebhookEvent({
payload: req.body, // the raw Buffer
header: req.headers['trovacast-signature'],
secrets: [process.env.TROVACAST_WEBHOOK_SECRET],
});
} catch {
return res.sendStatus(400);
}
// Deduplicate on event.id, then handle event.type — after answering.
res.sendStatus(200);
});import os
from flask import Flask, request
from trovacast.webhooks import TrovacastWebhookError, construct_webhook_event
app = Flask(__name__)
@app.post("/trovacast/webhook")
def webhook():
try:
event = construct_webhook_event(
payload=request.get_data(), # the raw bytes
header=request.headers.get("Trovacast-Signature"),
secrets=[os.environ["TROVACAST_WEBHOOK_SECRET"]],
)
except TrovacastWebhookError:
return "", 400
# Deduplicate on event["id"], then handle event["type"].
return "", 200v1 = hex( HMAC-SHA256( key = <your whsec_… secret, as UTF-8>,
message = "<t>.<raw request body>" ) )
Test vector:
secret whsec_AbCdEfGhIjKlMnOpQrStUvWxYz012345
t 1759750000
body {"object":"event","id":"evt_1"}
v1 4bcf66dbf78f9a8d432a6ba12cde5e6db0831e87934bb61807b680dadffe0db9Rotation: after POST /v1/webhook-endpoints/{endpointId}/rotate-secret, every delivery for the next 24 hours carries two v1 values — one per secret — so you can deploy the new secret whenever you like inside that window.
Retries, pausing and disabling
- Retries (each wait +0–10 % jitter): 1 min, 5 min, 30 min, 2 h, 5 h, 10 h, 12 h, 12 h, 15 h, 15 h — then the delivery is
failed, about 72 hours after the first attempt. - Pausing: after 3 failed attempts in a row an endpoint is paused — 30 seconds, doubling up to 15 minutes — then sent one delivery as a probe; a success resumes delivery. Only a successful delivery ends a pause; to check a fix at once, send a test event.
- Disabling: an endpoint failing continuously for 3 days becomes
failing_disabledand your webhook managers are notified. Its events keep being recorded: re-enabled within 3 days of an event it still receives it, and older ones can be resent in bulk or read back. - Fair delivery: a few deliveries are in flight per endpoint and per project at once, so a slow receiver delays only its own events. Replies, consent and account changes go ahead of status floods.
- A suspended project sends nothing until it is reactivated. Events and deliveries are kept 30 days.
Missed events
Every event recorded for your endpoints is kept 30 days and can be read back — the same envelope, id and data its deliveries carried — so an outage longer than the retry schedule, or a receiver that answered 2xx and then lost an event, costs nothing.
curl 'https://api.trovacast.com/v1/events?type=message.received&createdAfter=2026-11-04T00%3A00%3A00.000Z&limit=100' \
-H "Authorization: Bearer $TROVACAST_API_KEY"- Needs
webhooks:manageplus each event's own read scope; without it,?type=that event is403, and an unfiltered page leaves those events out. - Newest first, cursor-paginated. When polling, overlap each window by a minute and deduplicate on
id: an event commits with its change, so it can become visible a moment after itscreatedAt. - An event is recorded only when one of your endpoints — enabled or disabled — subscribed to its type. With none, reconcile from the resources instead (
updatedAfteron messages, calls and contacts). - Or have the failed deliveries sent again:
POST /v1/webhook-endpoints/{endpointId}/deliveries/resendwithsinceresends up to 1,000 at a time (hasMoresays to call again).
Per-request status callbacks
POST /v1/messages and POST /v1/calls take statusCallback: { url, events? }: that one message’s or call’s status events are also POSTed to url — in addition to your endpoints, never instead of them. A message’s are message.sent, message.delivered, message.read and message.failed; a call’s call.queued, call.ringing, call.answered, call.completed, call.failed, call.no_answer and call.busy — all of them when events is left out.
- Signed with your status-callback secret, one per mode: create it once with
POST /v1/status-callback-secret(webhooks:manage) — thewhsec_…secret is in that response only — and verify exactly as above. Calling it again rotates it, with the same 24-hour overlap. A request naming a callback before the secret exists is409 STATUS_CALLBACK_SECRET_MISSING. - The URL follows the endpoint rules (
https, a public host, an allowed port —400 WEBHOOK_URL_INVALID), checked when the request is accepted and at every delivery. Its query string is yours: put your own correlation there. - Delivery is the same engine’s: the same envelope and
id(dedupe it against your endpoints’), the same retries, at least once. A callback is bound before the message or call exists, so evencall.queuedreaches it; a refused request leaves none behind. It is kept 7 days, never listed under your endpoints and never counted against their limit. - Broadcasts take no per-request callback: subscribe an endpoint to
message.*instead.
curl -X POST 'https://api.trovacast.com/v1/messages' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: order-1001-shipped' \
-H 'Content-Type: application/json' \
-d '{
"type": "template",
"contactId": "CONTACT_ID",
"template": {
"name": "order_shipped",
"language": "en"
},
"variables": {
"var1": "#1001"
},
"statusCallback": {
"url": "https://apps.example.com/trovacast/status?order=1001",
"events": [
"message.delivered",
"message.failed"
]
}
}'One feed for an integration
An integration that provisions an organization per customer registers its own endpoints with its integration key (organizations:events): POST /v1/integration/webhook-endpoints takes the same body, and each such endpoint receives the events of every organization the integration provisioned, through the same engine — signature, retries, pausing, resends. Every envelope names the organization (organizationId) and your externalReference for it, so route on it without a lookup. An organization’s own endpoints keep working beside yours.
- It carries what Trovacast delegated to your integration: a type is subscribed only when every scope that reads it is delegated (
403 API_KEY_SCOPE_MISSINGnames the one missing), and a type the delegation stops covering is no longer delivered. - Modes: a live key’s endpoints get your live organizations’ live traffic; a test key’s get test traffic — your test organizations’ and your live ones’ test-mode traffic. At most 10 per mode.
- Missed events:
GET /v1/integration/eventsreads back the events of all your organizations, or one organization’s withorganizationId. - A test delivery to your endpoint names no organization (
organizationIdis the nil UUID) and carriesintegrationId: answer it2xxbefore routing by organization.
curl -X POST 'https://api.trovacast.com/v1/integration/webhook-endpoints' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"url": "https://apps.example.com/trovacast/events",
"events": [
"message.received",
"contact.consent.updated"
],
"description": "Every organization"
}'Event catalog
Each delivery's body is { object: "event", id, type, livemode, apiVersion, createdAt, organizationId, data } — livemode is false for test traffic (delivered to test endpoints only) and true otherwise, including events about what has no test side. The last column is what an API key needs to subscribe to the event or read it back.
| Event | When it is sent | Key scopes |
|---|---|---|
message.sent | The provider accepted a message you sent. WhatsApp (Meta), Amazon SES or the SMTP relay, or the SMS vendor accepted an outbound message. message.status is sent.data: message | messages:read |
message.delivered | A message reached the contact. The provider reported the message delivered to the contact’s phone or mailbox (for SMS: the vendor’s delivery receipt).data: message | messages:read |
message.read | The contact read a message. Meta reported the WhatsApp message read.data: message | messages:read |
message.failed | A message failed for good. message.failure carries { code, reason }. A scheduled message cancelled before it was sent fails with MESSAGE_CANCELED.data: message | messages:read |
message.received | A contact sent a message or tapped a reply button. An inbound message, with button for a tapped reply and context.messageId for a reply to one of yours. contact is the sender (needs contacts:read too).data: contact, message | messages:readcontacts:read |
message.complained | A recipient reported an email you sent as spam. The message’s status does not change (it was delivered); the address is suppressed and the contact’s email consent opted out, which its own contact.consent.updated reports.data: complaint, message | messages:read |
contact.consent.updated | A contact’s consent on a channel changed. WhatsApp, email or SMS consent moved — a STOP, an unsubscribe, a spam report, a reply, Meta’s own preference, or a write through the API or the console. consent.object names the channel.data: consent, livemode, source | contacts:read |
template.updated | Meta reviewed a template or changed its category or quality. change says which facet moved; template is as GET /v1/templates/{templateId} reads it.data: change, template | templates:read |
whatsapp.account.updated | The WhatsApp account changed. WhatsApp was connected or disconnected, or its credential, quality rating, display name, messaging limit or restriction changed.data: account, change | whatsapp:read |
call.queued | A call was handed to the carrier. The call was created and its dial handed to the carrier.data: call | calls:read |
call.ringing | The contact’s phone is ringing — or a routed inbound call is ringing someone. The carrier reports the contact’s phone ringing (ringing: null). On an inbound call its number’s flow routes, a connect step started ringing: ringing names who — each party by its place in the step’s targets and your reference, a number by its last four digits and the registered phone it is — and how (strategy). Once per party in a sequence, once for all at once.data: call, ringing | calls:read |
call.answered | The contact answered — or someone took a routed inbound call. The conversation is live (answeredBy: null for an outbound call’s own answer). On an inbound call its number’s flow routes, someone took the caller: answeredBy.target says who (a number by its last four digits and the registered phone it is, a seat, an app, the queue a seat took the caller from) and confirmed whether they pressed the connect’s confirm key. A pickup that never confirmed is never told.data: answeredBy, call | calls:read |
call.completed | A connected call ended. With call.durationSeconds and who hung up (call.hangup.side).data: call | calls:read |
call.failed | A call failed, or was cancelled before an answer. call.failure says why.data: call | calls:read |
call.no_answer | The contact did not answer. The call rang out unanswered.data: call | calls:read |
call.busy | The contact’s line was busy. The carrier reported the line busy.data: call | calls:read |
call.recording.ready | A call’s recording is stored. call.recording has its id, format and duration. No link rides on the event: fetch one from GET /v1/calls/{callId}/recording (recordings:read, which subscribing to this event also needs).data: call | calls:readrecordings:read |
conversation.opened | A conversation now waits for an answer. The customer’s first message on the thread, a customer message on a resolved thread, or an agent or API key reopening it. A reaction never opens one, nor does an outbound send.data: conversation, livemode, reason | conversations:read |
conversation.resolved | A conversation was marked handled. An agent or an API key resolved the thread.data: conversation, livemode | conversations:read |
message.media.ready | A file a contact sent is stored. message.media.status is ready: fetch a download link with GET /v1/messages/{messageId}/media. No link rides on the event.data: message | messages:read |
message.media.failed | A file a contact sent could not be stored. message.media.status is failed or rejected, with message.media.failureCode.data: message | messages:read |
call.inbound | A call to one of your numbers reached its route. The caller is on the line, routed to a flow, an application, a queue or an agent: the call has direction: inbound, to the number of yours they dialled (international format) with its numberId, and from the caller masked to their last four digits (•••• ••3210).data: call | calls:read |
call.held | A hold action put the caller on hold. Fired by the hold action.data: actionId, call | calls:read |
call.resumed | A resume action took the caller off hold. Fired by the resume action.data: actionId, call | calls:read |
call.transferred | A transfer connected the caller elsewhere. An outside number answered (its last four digits), or a call flow, a voice application or a queue took the call over.data: actionId, call, transfer | calls:read |
call.gather.completed | A gather action finished. With the keys pressed or what the caller said — never the digits of a sensitive gather.data: actionId, call, gather | calls:read |
call.flow.failed | A call’s flow failed and the call was hung up. The platform hung up rather than leave the caller on a silent line. call.failure carries the documented FLOW_* code; flow says where it failed.data: call, flow | calls:read |
call.machine_detected | The carrier told a person from an answering machine. On a call that asked (machineDetection): call.machineDetection.result is human, machine or unknown. Once per call.data: call | calls:read |
conference.participant.joined | A party joined a conference. A dialled number answered, or an agent accepted. Once per party.data: conference, participant | calls:read |
conference.participant.left | A party left a conference. It hung up, or was removed. Once per party.data: conference, participant | calls:read |
conference.ended | A conference’s call ended. Its participants show who was still on. Once per conference.data: conference | calls:read |
call.transcript.ready | A call’s transcript is complete. Read it with GET /v1/calls/{callId}/transcript (transcripts:read, which subscribing also needs): the event counts the segments, never carries the text. Fires only when something was transcribed.data: call, transcript | calls:readtranscripts:read |
call.summary.ready | The AI summarised and graded a call. summary is what GET /v1/calls/{callId}/summary returns (status: ready). Once per call; an agent’s later wrap-up fires no second event. An AI agent’s test call fires it too, with the sandbox’s mock summary of its scripted conversation (summary.mock: true).data: call, summary | calls:readtranscripts:read |
email.opened | A person first opened a tracked email. Once per message; machine opens (privacy proxies, security scanners) are never reported.data: message, open | messages:read |
email.clicked | A person first clicked a tracked link of an email. Once per link.data: click, message | messages:read |
balance.low | Spend took the prepaid balance below its low-balance threshold. Once per crossing: it fires again only after a top-up lifts the balance back over the threshold and spend takes it under again.data: balance, crossedBy | billing:read |
number.port_request.updated | A port-in request moved. Submitted, in review, approved (with the carrier’s date once known), rejected (with the platform’s note), completed (the numbers are yours) or cancelled. portRequest is what GET /v1/numbers/port-requests/{portRequestId} reads.data: portRequest, previousStatus | numbers:read |
call.transcript.segmentOpt-in | One line of a live call’s transcript. As soon as it is stored: the item GET /v1/calls/{callId}/transcript lists, phone numbers masked to their last four digits. Opt-in — sent only to an endpoint that names it — because it fires once per utterance. Deliveries are not ordered: order by segment.sequence. Never sent for what is said while a sensitive gather is open.data: callId, livemode, segment | calls:readtranscripts:read |
verify.approved | A one-time code was checked right. verify.status is approved. Once per verification; never the code.data: verify | verify:read |
verify.expired | A one-time code ran out before the right one was checked. verify.status is expired. Once per verification.data: verify | verify:read |
dlt.entity.updated | A DLT principal entity was registered, corrected or reviewed. Registered (pending), corrected (back to pending), or reviewed by the platform: verified, rejected (with entity.reviewNote) or suspended. entity is what GET /v1/dlt/entities/{entityId} reads, its headers included. Once per version.data: entity | dlt:read |
dlt.header.updated | A DLT header was registered or reviewed. An SMS header or a 140/160-series voice header was registered or reviewed by the platform. header is what GET /v1/dlt/headers/{headerId} reads. Once per version.data: header | dlt:read |
sms.sender.updated | An SMS sender’s status moved. Registered (pending_verification), activated, restricted or disabled by the platform, restricted or reactivated with its number (a long code), or sent back to pending_verification because the organization’s DLT entity changed. sender is what GET /v1/sms/senders/{senderId} reads. Once per version.data: sender | sms:read |
dlt.contest.updated | Your claim on a DLT header value another organization held moved. A POST /v1/dlt/headers answered 409 DLT_REGISTRATION_CLAIMED while another organization held the value: the claim waits for the platform (opened), the value became free while it waits — the claim stays open for the platform, and nothing is said about the holder (holder_gone), the platform recorded the header for you (awarded, headerId — GET /v1/dlt/headers/{headerId}), or kept the value with its holder or another claim (dismissed). Never names the holder. Once per version of the claim.data: contest, headerId, outcome | dlt:read |
sms.sender_contest.updated | Your claim on an SMS sender another organization held moved. A POST /v1/sms/senders answered 409 SMS_SENDER_CLAIMED while another organization held the header live: the claim waits for the platform (opened), the header became free while it waits — the claim stays open for the platform, and nothing is said about the holder (holder_gone), the platform registered the sender for you (awarded, senderId — GET /v1/sms/senders/{senderId}, pending_verification), or kept it with its holder or another claim (dismissed). Never names the holder. Once per version of the claim.data: contest, outcome, senderId | sms:read |
call.rated | A call’s charge was written. call.charge is the charge as GET /v1/calls/{callId} reads it — status (charged, waived or not_connected), amount, minutes, and the rule and reason it was rated by. A call is rated after its final call.* event, which carries charge: null. Once when it is rated; an unrated charge (no price yet) fires nothing until a re-rate or the backfill charges it, and a charged call fires again only when it is re-rated on corrected minutes. A test call is never rated, so it never fires.data: call | calls:read |
call.missed | An inbound caller reached nobody. Every route the call tried went unanswered, the caller hung up waiting, or the business was closed. missed.reason says which; missed.voicemail is the message they left, when they left one (its audio is the call’s recording). Once per call, when its flow ends — the call’s own final event (call.completed) is separate. Text them back, or call them back, from here.data: call, missed | calls:read |
call.voicemail.ready | A caller’s message is ready, with its transcript. The voicemail a caller left: its audio (voicemail.recordingId, fetched with GET /v1/calls/{callId}/recording?recordingId=), the key they pressed (voicemail.key) and — when the voicemail step asked — their words from the call’s live transcript (voicemail.transcript, phone numbers masked to their last four digits). Once per voicemail, a few seconds after the message ends, when the transcript of it has landed; it can come after the call’s call.missed. Needs transcripts:read as well as calls:read.data: call, voicemail | calls:readtranscripts:read |
call.ai.transfer | An AI call’s agent handed the caller to a person. The call names a transfer (its own, its ai route’s, or its session webhook’s) and its agent asked for a person. transfer.outcome is answered (the person has the caller and the agent left the call), no_answer or failed (cause says why: NO_ANSWER, BUSY, UNCONFIRMED, or the dial’s refusal such as DESTINATION_BLOCKED) — then the caller is back with the agent (returnedToAi). Once per hand-off (transfer.id); a call can hand off again after coming back.data: call, transfer | calls:read |
call.ai.opt_out | An AI call’s caller opted out and was marked do-not-call. The caller pressed the call’s opt-out key (optOut.method: dtmf, key) or said one of its phrases (speech, phrase — the configured phrase, never their words). The contact was marked do-not-call in the same transaction (optOut.doNotCall; the contact reads doNotContact: true and every call to them is refused CONTACT_DO_NOT_CALL), then the agent said the reply and the call ended. Once per call.data: call, optOut | calls:read |
call.dtmfOpt-in | A key the caller pressed during an AI conversation, or a flow that tells keys. Opt-in: sent only to endpoints that name it. One per key the caller pressed during an AI conversation (an AI call, or an AI step of a flow) or — P7 — during the steps of a flow that opts in (events: { dtmf: true }) — never one pressed into a sensitive gather.data: call, dtmf | calls:read |
sms.registration.updated | A US 10DLC brand, campaign or number assignment moved. A registration made with POST /v1/sms/brands, POST /v1/sms/campaigns or POST /v1/sms/campaigns/{campaignId}/numbers was created (previousStatus: null, pending), filed with the registry or put to the platform’s review (submitted), approved, rejected (statusReason says why), expired (a campaign) or removed (a number taken off its campaign). A number assignment approved activates the number’s SMS sender (senderId, told as sms.sender.updated); one removed, or whose campaign stopped being approved, sends it back to pending_verification. Read the registration itself with its GET. Once per version.data: registration | sms:read |
number.updated | A number its carrier was reviewing was approved or rejected. A number you ordered that its carrier bought for you but held for the regulator’s review (pendingCompliance: true, the order’s pending.code NUMBER_PENDING_COMPLIANCE) — compliance_approved: activated and charged (activated: true, status: assigned), or still on hold with a fresh reservedUntil and pending saying why (activate it with POST /v1/numbers/{numberId}/activate once that is fixed); compliance_rejected: handed back to the carrier, nothing charged, the number no longer yours (status: available, reason the carrier’s). Once per review.data: change, number | numbers:read |
number.port_out.updated | A number unlocked for another carrier moved. T7: a port-out made with POST /v1/numbers/{numberId}/port-out — unlocked (previousStatus: null; again, previousStatus: unlocked, for a new PIN or once the gaining carrier and its focDate are known), completed (the number left the platform: no longer yours, no further rentals), failed (refused or given up, or its PIN expired — failure.code PIN_EXPIRED — and the number relocked, still yours) or cancelled (you relocked it, or released the number). Never carries the PIN. Once per version.data: portOut, previousStatus | numbers:read |
message.failedcarriesmessage.failure = { code, reason }, including failures before the provider (consent, window, template, suppression, billing) and outcomes that are unknown (SUBMISSION_UNKNOWN— never re-sent; a WhatsApp one that Meta did accept is followed bymessage.sentand later statuses).message.receivedcarries{ message, contact }; reply on the thread withconversationId. A file the contact sent is fetched withGET /v1/messages/{messageId}/mediaoncemessage.media.readyarrives.contact.consent.updatedcarries{ consent, source }—sourceisstop_keyword,start_keyword,unsubscribe_link,spam_complaint,inbound_message,meta_preference,meta_131050,apiorconsole— and is sent only when the consent actually changed, so re-syncing your own state never echoes back.whatsapp.account.updatedcarries{ account, change }withchangeone ofconnected,disconnected,credential,quality,name,limit,restricted. Readaccount.statusto decide whether it can send.call.completedcarriescall.durationSecondsandcall.hangup;call.recording.readycarries no link — fetch one fromGET /v1/calls/{callId}/recording.POST /v1/webhook-endpoints/{endpointId}/testsends a syntheticwebhook.testevent, signed like any delivery and stored nowhere (5 a minute per endpoint).
- POST
/v1/webhook-endpointsRegisters a webhook endpoint; the response carries its secret once - GET
/v1/webhook-endpointsLists the organization’s webhook endpoints - GET
/v1/webhook-endpoints/{endpointId}Retrieves a webhook endpoint - PATCH
/v1/webhook-endpoints/{endpointId}Changes a webhook endpoint’s URL, events, description or status - DELETE
/v1/webhook-endpoints/{endpointId}Deletes a webhook endpoint and its pending deliveries - POST
/v1/webhook-endpoints/{endpointId}/rotate-secretIssues a new signing secret; the previous one keeps signing for 24 hours - POST
/v1/webhook-endpoints/{endpointId}/testSends a signed `webhook.test` event now and reports the endpoint’s answer - GET
/v1/webhook-endpoints/{endpointId}/deliveriesLists an endpoint’s recent deliveries, newest first; filter by status - POST
/v1/webhook-endpoints/{endpointId}/deliveries/{deliveryId}/resendSends a delivery again now, with a fresh retry schedule - POST
/v1/webhook-endpoints/{endpointId}/deliveries/resendSends an endpoint’s failed (or retry-waiting) deliveries again now, in bulk - GET
/v1/eventsLists the organization’s stored events (the last 30 days), newest first - GET
/v1/events/{eventId}Retrieves a stored event by its id - GET
/v1/status-callback-secretThe status-callback signing secret of the key’s mode, without the secret - POST
/v1/status-callback-secretCreates (or rotates) the status-callback signing secret; the response carries it once
| Code | Status | Meaning and what to do |
|---|---|---|
API_KEY_SCOPE_MISSING | 403 | The key lacks the scope the endpoint (or a webhook event) requires; requiredScope names it. See Scopes.What to do: Use a key that holds requiredScope: a project administrator creates one in Settings → Developers (an existing key's scopes can be narrowed, never widened). Retrying with this key cannot succeed. |
CONFLICT | 409 | The resource's state does not allow this, there is a uniqueness clash, or it changed concurrently.What to do: Read the resource again, then decide: retry against its current state (with its new version where it has one), or choose another value for a uniqueness clash. |
RATE_LIMITED | 429 | Too many requests. Also a webhook test past its endpoint's budget, or a webhook URL past the project's hourly budget. See Rate limits.What to do: Wait Retry-After seconds, then retry the same request — with the same Idempotency-Key on a write — backing off exponentially with jitter if it repeats. See Backing off. |
STATUS_CALLBACK_SECRET_MISSING | 409 | A send or call carried a statusCallback before the project had a status-callback signing secret for the key’s mode.What to do: Create the secret once with POST /v1/status-callback-secret (scope webhooks:manage) and store it — it is in that response only — then retry. See Per-request status callbacks. |
WEBHOOK_DELIVERY_IN_FLIGHT | 409 | A resend of a delivery that is being attempted at this moment.What to do: Wait for the attempt to finish, then check the delivery (GET /v1/webhook-endpoints/{endpointId}/deliveries) and resend it only if it failed. |
WEBHOOK_ENDPOINT_DISABLED | 409 | A resend (one or in bulk) on an endpoint that is not enabled.What to do: Enable the endpoint first — PATCH /v1/webhook-endpoints/{endpointId} with status: "enabled" — then resend. |
WEBHOOK_ENDPOINT_LIMIT | 409 | The project already has the most webhook endpoints it may have (10).What to do: Delete an endpoint you no longer need (DELETE /v1/webhook-endpoints/{endpointId}), or subscribe an existing one to more events with PATCH /v1/webhook-endpoints/{endpointId}. |
WEBHOOK_URL_INVALID | 400 | The webhook URL is not allowed; reason says why: URL_INVALID, URL_NOT_ALLOWED, DNS_FAILED, ADDRESS_NOT_ALLOWED or PORT_NOT_ALLOWED. See Webhooks.What to do: Register an https:// URL with no credentials in it, on a public host that resolves to public addresses, on port 443, 80 or 1024 and up (not a database or other non-HTTP service port). The same URL fails the same way. |