Webhooks
Hear when a call starts and ends, is analysed or recorded, and when a meeting bot joins, without polling.
Webhooks tell your servers what happened, the moment it is final: a call started, a call ended with its charge and transcript, its analysis is ready, a meeting bot got in. Each event is a signed POST of JSON to an https address of yours, retried for about three days until you answer 2xx.
You manage endpoints here with a secret key, or in the dashboard on the API keys page, under Webhooks.
Add an endpoint
/v1/webhookscurl https://talk.madein10.com/v1/webhooks \
-H "Authorization: Bearer $ACME_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/hooks/calls",
"description": "our CRM",
"event_types": ["call.ended", "call.analyzed"]
}'It answers 201 with the endpoint and its signing secret, whsec_…. The secret is shown this once (and again only when you rotate it): keep it to check signatures.
{
"webhook": {
"id": "whe_6Tn1Vb8XcK3mPq9LsD2f",
"url": "https://example.com/hooks/calls",
"description": "our CRM",
"event_types": ["call.ended", "call.analyzed"],
"env": "live",
"enabled": true,
"disabled_reason": null,
"failing_since_unix": null,
"previous_secret_until_unix": null,
"created_unix": 1793300000,
"updated_unix": 1793300000
},
"secret": "whsec_BwgJCgsMDQ4PEBESExQVFhcYGRobHB0eHyAhIiMkJSY="
}The rules
url: https only, at most 2,000 characters, no#fragment(400invalid_url). Its name must resolve, and every address it resolves to must be public: private networks, loopback, link-local and cloud metadata addresses, and the like are refused (400unsafe_url). It is checked again before every delivery.event_types: the events it takes, from the table below. Empty, the default, takes them all, including types added later. An unknown type is 400invalid_field.env: an endpoint belongs to your key's env. A live key makes and sees live endpoints, which get live calls' events; a test key, test ones, which get test calls' events. Naming the other env is 400invalid_field.- 10 endpoints per organization, live and test together (409
webhook_limit). enabled: falseturns it off. Its events wait (paused, for up to the 30 days events are kept) and go at once when you turn it back on.
Manage endpoints
| Endpoint | What it does |
|---|---|
GET /v1/webhooks | Your env's endpoints: { "data": [...] } |
GET /v1/webhooks/{webhook_id} | One endpoint (never its secret) |
PATCH /v1/webhooks/{webhook_id} | Change url, description, event_types or enabled. A new url gets a fresh start on failures |
DELETE /v1/webhooks/{webhook_id} | Deletes it and its deliveries: { "id": "whe_…", "deleted": true } |
POST /v1/webhooks/{webhook_id}/rotate | A new secret; the old one also signs for grace_seconds. See Signatures |
POST /v1/webhooks/{webhook_id}/test | Sends a webhook.test now and answers what your endpoint said |
GET /v1/webhooks/{webhook_id}/deliveries | What was sent to it, newest first. See Retries |
POST /v1/webhooks/deliveries/{delivery_id}/retry | Sends one delivery again now |
Test works while the endpoint is off. It waits up to 10 seconds for your answer, is never retried, and never counts as a failure:
{ "delivered": false, "status_code": 500, "error": "it answered 500", "event_id": "evt_7Rc2Yj5LmT9pQw3NdF6k", "delivery_id": "whd_5Hs9Fk2PvX7nCb1QzW4r" }Events
Every delivery is a POST of one JSON shape, compact, with its keys in alphabetical order:
{ "id": "evt_…", "type": "call.ended", "created_unix": 1793300100, "data": { … } }type | Sent when | data |
|---|---|---|
call.started | A call has started and the browser can connect | The call (status waiting) |
call.ended | A call has settled: once per call, also for one that never started | The call, with reason and transcript |
call.analyzed | A call's analysis is ready, or failed for good: once per call, never when there was nothing to analyse | call_id, character_id, env, status, summary, fields, verdict, reason, error, metadata, analyzed_unix |
request.updated | We moved a custom-character request of yours to another status | The request, with previous_status |
meeting.waiting_room | A meeting bot is waiting to be let in: once per meeting, the first time it waits | The meeting (waiting_room: true) |
meeting.joined | A meeting bot got in: once per meeting | The meeting (status in_meeting) |
meeting.ended | It was in and left, or it was called off: once per meeting | The meeting (status ended, with reason) |
meeting.failed | It never got in: once per meeting, never with meeting.ended | The meeting (status failed, with reason) |
recording.ready | A call's recording is final: once per call | call_id, character_id, source, env, metadata, seconds, bytes, created_unix, settled_unix, ready_unix |
webhook.test | Someone pressed Test, to that endpoint only | endpoint_id, message |
Live calls' events go to live endpoints and test calls' to test endpoints, whichever way the call started (/v1, the dashboard, the website widget or a meeting). request.updated goes to live endpoints.
The reference has the full schema of every event in the table above.
The call in an event
call.started and call.ended carry the call without error and end_reason; call.ended has reason instead, and the transcript:
{
"id": "evt_3Kp8Zr1WqN6xBv4MhS9a",
"type": "call.ended",
"created_unix": 1793300100,
"data": {
"id": "call_2Gx7Mb9KpQ4sVn1ZrT6e",
"character_id": "chr_4fT9kQ2mXw7LbN3pZs8V",
"character_name": "Alex",
"status": "ended",
"reason": "completed",
"source": "api",
"env": "live",
"max_seconds": 300,
"billed_seconds": 94,
"charged_usd": 0.94,
"price_per_min_usd": 0.6,
"metadata": { "ticket": 7 },
"created_unix": 1793300000,
"settled_unix": 1793300100,
"transcript": [
{ "n": 1, "customer": "", "ai": "Hi, I'm Alex, an AI assistant…" },
{ "n": 2, "customer": "…", "ai": "…" }
]
}
}reason is ours, short, and never another system's words: completed (it ran and ended: hung up, ended through the API, or out of time), never_connected (it ended without the browser connecting), and for status: "failed": not_started (it couldn't start; POST /v1/calls already answered 503 and no call.started was sent), interrupted (we lost the call), error (it failed on our side). Only a call that connected and played a reply is charged. More reasons may come: treat one you don't know by its status.
Never lost, never twice
- An event is written together with the change it reports (the call settling, the call starting), so it can't be lost after the change, or sent for a change that didn't happen.
- Once per call. A call settles once, and
call.ended,call.analyzed,recording.readyand the meeting events are each written once. - Only for endpoints that take it. An endpoint added later doesn't get earlier events.
- At least once, in no guaranteed order. A retry or a replay can bring an event twice: dedupe on the
webhook-idheader, which is the event's id. When an event andGET /v1/calls/{call_id}disagree, theGETis right.