POST /webhooks

Create a webhook subscription

Scope	webhooks:write
Cost	Free

enabled defaults to false, so a half-configured integration cannot start firing at an endpoint that is not ready.

Returns 201 with a Location header pointing at the new subscription.

Request body

Field	Type	Required	Description
name	string	yes	Required, non-empty.
description	string	no
url	string	yes	Required. Must use http or https and include a host.
type	AccountRealTimeCalls | AccountEndedCalls | UserEndedCalls | AccountSMS | AccountAITranscription	yes	The event a subscription fires on. Fetch the live list from GET /webhooks/types.
enabled	boolean	no	Defaults to false so nothing fires at an endpoint that is not ready.

{
  "name": "My hook",
  "url": "https://example.com/hook",
  "type": "AccountSMS",
  "enabled": true
}

Responses

201

Created.

Field	Type	Description
id	integer
name	string
description	string
url	string	Where events are delivered. http or https, max 1024 characters.
type	AccountRealTimeCalls | AccountEndedCalls | UserEndedCalls | AccountSMS | AccountAITranscription	The event a subscription fires on. Fetch the live list from GET /webhooks/types.
enabled	boolean	Whether events are being delivered.
createdAt	string (RFC 3339)
updatedAt	string (RFC 3339)

Errors

Status	Meaning
400	invalid_request — a missing or malformed field, an unknown enum value, or an unknown field in the body. Nothing was charged.
401	unauthenticated — no credential, or one that is invalid, revoked or expired. The WWW-Authenticate header names the scope the endpoint wanted.
403	Two different failures share this status, and the type tells them apart:
500	internal_error — something failed on our side. For a send, nothing was charged, guaranteed, which is what makes a retry safe.

See Errors for the full catalog and what to do about each.

Example

curl -X POST 'https://api.account.telebroad.com/api/public/v1/webhooks' \
  -H "Authorization: Bearer $TB_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"My hook","url":"https://example.com/hook","type":"AccountSMS","enabled":true}'

Try it in the playground →