Trovacast

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

Create 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"
}'
201 Created — the secret is shown only here (json)
{
  "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 400 WEBHOOK_URL_INVALID with reason: "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

A delivery (http)
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 2xx within 10 seconds. Anything else — another status (a 3xx too), a timeout, a refused connection — is a failure. Answer fast and do the work afterwards.
  • At least once: deduplicate on the envelope id (also Trovacast-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 (read without delivered): treat each as "now at least this far" and read message.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.

  1. Read the raw body.
  2. Split the header on ,; take t and every v1.
  3. Reject if |now − t| is more than 300 seconds (the replay window).
  4. Compute the HMAC with each secret you hold and compare it, in constant time, with every v1. Accept if any matches.
Node.js (with the SDK) (javascript)
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);
});
Python (with the SDK) (python)
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 "", 200
Any language: the rule (text)
v1 = 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      4bcf66dbf78f9a8d432a6ba12cde5e6db0831e87934bb61807b680dadffe0db9

Rotation: 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_disabled and 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.

Events since a moment
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:manage plus each event's own read scope; without it, ?type= that event is 403, 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 its createdAt.
  • An event is recorded only when one of your endpoints — enabled or disabled — subscribed to its type. With none, reconcile from the resources instead (updatedAfter on messages, calls and contacts).
  • Or have the failed deliveries sent again: POST /v1/webhook-endpoints/{endpointId}/deliveries/resend with since resends up to 1,000 at a time (hasMore says 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) — the whsec_… 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 is 409 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 even call.queued reaches 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.
Hear about one message
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_MISSING names 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/events reads back the events of all your organizations, or one organization’s with organizationId.
  • A test delivery to your endpoint names no organization (organizationId is the nil UUID) and carries integrationId: answer it 2xx before routing by organization.
Hear every organization’s events
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.

EventWhen it is sentKey scopes
message.sentThe 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: messagemessages:read
message.deliveredA 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: messagemessages:read
message.readThe contact read a message. Meta reported the WhatsApp message read.data: messagemessages:read
message.failedA message failed for good. message.failure carries { code, reason }. A scheduled message cancelled before it was sent fails with MESSAGE_CANCELED.data: messagemessages:read
message.receivedA 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, messagemessages:readcontacts:read
message.complainedA 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, messagemessages:read
template.updatedMeta 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, templatetemplates:read
whatsapp.account.updatedThe WhatsApp account changed. WhatsApp was connected or disconnected, or its credential, quality rating, display name, messaging limit or restriction changed.data: account, changewhatsapp:read
call.queuedA call was handed to the carrier. The call was created and its dial handed to the carrier.data: callcalls:read
call.ringingThe 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, ringingcalls:read
call.answeredThe 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, callcalls:read
call.completedA connected call ended. With call.durationSeconds and who hung up (call.hangup.side).data: callcalls:read
call.failedA call failed, or was cancelled before an answer. call.failure says why.data: callcalls:read
call.no_answerThe contact did not answer. The call rang out unanswered.data: callcalls:read
call.busyThe contact’s line was busy. The carrier reported the line busy.data: callcalls:read
call.recording.readyA 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: callcalls:readrecordings:read
conversation.openedA 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, reasonconversations:read
conversation.resolvedA conversation was marked handled. An agent or an API key resolved the thread.data: conversation, livemodeconversations:read
message.media.readyA 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: messagemessages:read
message.media.failedA file a contact sent could not be stored. message.media.status is failed or rejected, with message.media.failureCode.data: messagemessages:read
call.inboundA 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: callcalls:read
call.heldA hold action put the caller on hold. Fired by the hold action.data: actionId, callcalls:read
call.resumedA resume action took the caller off hold. Fired by the resume action.data: actionId, callcalls:read
call.transferredA 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, transfercalls:read
call.gather.completedA gather action finished. With the keys pressed or what the caller said — never the digits of a sensitive gather.data: actionId, call, gathercalls:read
call.flow.failedA 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, flowcalls:read
call.machine_detectedThe 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: callcalls:read
conference.participant.joinedA party joined a conference. A dialled number answered, or an agent accepted. Once per party.data: conference, participantcalls:read
conference.participant.leftA party left a conference. It hung up, or was removed. Once per party.data: conference, participantcalls:read
conference.endedA conference’s call ended. Its participants show who was still on. Once per conference.data: conferencecalls:read
call.transcript.readyA 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, transcriptcalls:readtranscripts:read
call.summary.readyThe 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, summarycalls:readtranscripts:read
email.openedA person first opened a tracked email. Once per message; machine opens (privacy proxies, security scanners) are never reported.data: message, openmessages:read
email.clickedA person first clicked a tracked link of an email. Once per link.data: click, messagemessages:read
balance.lowSpend 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, crossedBybilling:read
number.port_request.updatedA 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, previousStatusnumbers:read
call.transcript.segmentOpt-inOne 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, segmentcalls:readtranscripts:read
verify.approvedA one-time code was checked right. verify.status is approved. Once per verification; never the code.data: verifyverify:read
verify.expiredA one-time code ran out before the right one was checked. verify.status is expired. Once per verification.data: verifyverify:read
dlt.entity.updatedA 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: entitydlt:read
dlt.header.updatedA 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: headerdlt:read
sms.sender.updatedAn 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: sendersms:read
dlt.contest.updatedYour 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, outcomedlt:read
sms.sender_contest.updatedYour 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, senderIdsms:read
call.ratedA 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: callcalls:read
call.missedAn 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, missedcalls:read
call.voicemail.readyA 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, voicemailcalls:readtranscripts:read
call.ai.transferAn 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, transfercalls:read
call.ai.opt_outAn 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, optOutcalls:read
call.dtmfOpt-inA 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, dtmfcalls:read
sms.registration.updatedA 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: registrationsms:read
number.updatedA 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, numbernumbers:read
number.port_out.updatedA 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, previousStatusnumbers:read
  • message.failed carries message.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 by message.sent and later statuses).
  • message.received carries { message, contact }; reply on the thread with conversationId. A file the contact sent is fetched with GET /v1/messages/{messageId}/media once message.media.ready arrives.
  • contact.consent.updated carries { consent, source } — source is stop_keyword, start_keyword, unsubscribe_link, spam_complaint, inbound_message, meta_preference, meta_131050, api or console — and is sent only when the consent actually changed, so re-syncing your own state never echoes back.
  • whatsapp.account.updated carries { account, change } with change one of connected, disconnected, credential, quality, name, limit, restricted. Read account.status to decide whether it can send.
  • call.completed carries call.durationSeconds and call.hangup; call.recording.ready carries no link — fetch one from GET /v1/calls/{callId}/recording.
  • POST /v1/webhook-endpoints/{endpointId}/test sends a synthetic webhook.test event, signed like any delivery and stored nowhere (5 a minute per endpoint).
CodeStatusMeaning and what to do
API_KEY_SCOPE_MISSING403The 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.
CONFLICT409The 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_LIMITED429Too 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_MISSING409A 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_FLIGHT409A 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_DISABLED409A 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_LIMIT409The 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_INVALID400The 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.