Made in 10Docs
GuidesAPI
Webhooks

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

POST/v1/webhooks
curl 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.

Answer
{
  "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 (400 invalid_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 (400 unsafe_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 400 invalid_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 400 invalid_field.
  • 10 endpoints per organization, live and test together (409 webhook_limit).
  • enabled: false turns 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

EndpointWhat it does
GET /v1/webhooksYour 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}/rotateA new secret; the old one also signs for grace_seconds. See Signatures
POST /v1/webhooks/{webhook_id}/testSends a webhook.test now and answers what your endpoint said
GET /v1/webhooks/{webhook_id}/deliveriesWhat was sent to it, newest first. See Retries
POST /v1/webhooks/deliveries/{delivery_id}/retrySends 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:

Test result
{ "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:

Event
{ "id": "evt_…", "type": "call.ended", "created_unix": 1793300100, "data": { … } }
typeSent whendata
call.startedA call has started and the browser can connectThe call (status waiting)
call.endedA call has settled: once per call, also for one that never startedThe call, with reason and transcript
call.analyzedA call's analysis is ready, or failed for good: once per call, never when there was nothing to analysecall_id, character_id, env, status, summary, fields, verdict, reason, error, metadata, analyzed_unix
request.updatedWe moved a custom-character request of yours to another statusThe request, with previous_status
meeting.waiting_roomA meeting bot is waiting to be let in: once per meeting, the first time it waitsThe meeting (waiting_room: true)
meeting.joinedA meeting bot got in: once per meetingThe meeting (status in_meeting)
meeting.endedIt was in and left, or it was called off: once per meetingThe meeting (status ended, with reason)
meeting.failedIt never got in: once per meeting, never with meeting.endedThe meeting (status failed, with reason)
recording.readyA call's recording is final: once per callcall_id, character_id, source, env, metadata, seconds, bytes, created_unix, settled_unix, ready_unix
webhook.testSomeone pressed Test, to that endpoint onlyendpoint_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:

call.ended
{
  "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.ready and 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-id header, which is the event's id. When an event and GET /v1/calls/{call_id} disagree, the GET is right.

Next

On this page