Add a webhook endpoint

Must be a public https:// URL — private and link-local addresses are refused at save time rather than discovered at delivery time. The signing secret is returned once, here. Subscribe only to what you consume: every delivery is retried up to 14 times over roughly a day.

Requires the admin scope. A key with less gets 403 insufficient_scope.

Authorization

AuthorizationBearer <token>

Authorization: Bearer tone_live_… or tone_test_…. The prefix IS the environment: a test key reaches only the sandbox, and no request field bridges the two.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

description?string

Your label for this endpoint. Shown in the delivery log.

Lengthlength <= 120

enabled?boolean

Whether deliveries are sent. Disable to stop delivery without losing the endpoint, its secret or its history.

events?array<>

Which events to send to this endpoint. Subscribe only to what you consume — every delivery is retried up to 14 times over roughly a day, and 20 consecutive failures across all deliveries disables the endpoint. Open set — handle an unrecognised value rather than throwing. Today: call.initiated, call.answered, call.completed, call.failed, campaign.completed, campaign.paused, compliance.check.blocked, wallet.balance.low, number.suspended, number.reactivated, knowledge.build.completed, knowledge.build.failed.

Items1 <= items

Default

[  "call.completed"]

url*string

Where to POST deliveries. Must be a public https:// URL — private and link-local addresses are refused at save time rather than discovered at delivery time. Answer 2xx within 10 seconds; anything slower is retried and will manufacture duplicates.

Formaturi

Lengthlength <= 2048

Response Body

`application/json`

curl -X POST "https://example.com/v1/integrations/webhooks" \  -H "Content-Type: application/json" \  -d '{    "description": "Production CRM sync",    "enabled": true,    "events": [      "call.completed",      "call.failed"    ],    "url": "https://hooks.example.com/tone"  }'

{  "data": {    "consecutiveFailures": 0,    "createdAt": "2026-08-25T09:14:22Z",    "description": "Production — order service",    "disabledReason": null,    "enabled": true,    "events": [      "call.completed",      "campaign.finished"    ],    "id": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451",    "secret": "whsec_3f1a7f6e2b4c4d1e9a8b5c6d7e8f9a0b",    "url": "https://hooks.acme.example/tone"  }}

Was this page helpful?

Add a webhook endpoint

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`