Webhooks - Contour

Managing endpoints

Method	Path
`POST`	`/v1/webhook-endpoints`	Create. Returns the signing secret once.
`GET`	`/v1/webhook-endpoints`	List.
`GET`	`/v1/webhook-endpoints/{id}`	One endpoint.
`PATCH`	`/v1/webhook-endpoints/{id}`	Change `url`, `events`, `agent_ids`, `description`, `enabled`.
`DELETE`	`/v1/webhook-endpoints/{id}`	Stop deliveries. History is kept.
`POST`	`/v1/webhook-endpoints/{id}/rotate-secret`	New secret, shown once. The old one stops working immediately.
`POST`	`/v1/webhook-endpoints/{id}/test`	Send a sample event now. See Testing your endpoint.
`GET`	`/v1/webhook-endpoints/{id}/deliveries`	Delivery log. Filters: `call_id`, `event`, `status`, `page`, `page_size`.
`GET`	`/v1/webhook-endpoints/{id}/deliveries/{delivery_id}`	One delivery with the payload sent and every attempt.
`POST`	`/v1/webhook-endpoints/{id}/deliveries/{delivery_id}/retry`	Queue another attempt now.

Create:

POST /v1/webhook-endpoints
{
  "url": "https://example.com/webhooks/contour",
  "events": ["call.started", "call.ended", "call.analyzed"],
  "agent_ids": ["3f1c1b2e-..."],
  "description": "Production"
}

201
{
  "id": "b7e1...",
  "url": "https://example.com/webhooks/contour",
  "events": ["call.started", "call.ended", "call.analyzed"],
  "agent_ids": ["3f1c1b2e-..."],
  "enabled": true,
  "secret_hint": "k9Qz",
  "secret": "whsec_....................",
  "created_at": "...", "updated_at": "..."
}

The URL must be https and publicly reachable. Private and loopback addresses are rejected.
agent_ids limits the endpoint to calls made by those agents. Omit it to receive events for every call in your organization, including calls started from the Contour dashboard. Use the source field on the call object to tell them apart.
secret appears in this response and in rotate-secret only. Store it in your webhook handler’s configuration.

Events

Event	When	What’s filled in
`call.started`	We accepted your `POST /v1/calls` and began dialing. Not “answered”.	`status: queued`, numbers, `variables`, `metadata`.
`call.ended`	The call finished, before any analysis. Usually within seconds of hangup.	`disposition`, `duration_ms`, `disconnection_reason`, `recording_url`. `analysis: null`.
`call.analyzed`	Summary and structured extraction are ready. Usually 5–30s after `call.ended`.	Everything, including `analysis`.

Request format

POST https://example.com/webhooks/contour
Content-Type: application/json
User-Agent: Contour-Webhooks/1.0
X-Contour-Event: call.ended
X-Contour-Delivery-Id: 6a0d...-...
X-Contour-Signature: t=1725900000,v1=3f9a...

{
  "event": "call.ended",
  "id": "6a0d...",
  "created_at": "2026-09-10T14:04:36+00:00",
  "call": { ...call object... }
}

The call key is the full call object.

Respond with any 2xx within 10 seconds. The body is ignored. Do your real work after responding, or in a queue: a slow handler looks like a failure to us and gets retried.

Webhook requests do not carry your API key. They are authenticated by the signature header instead. See Verifying signatures.