Skip to main content

POST /webhooks

Create a webhook subscription

Scopewebhooks:write
CostFree

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

Returns 201. The Location header on the response — a standard HTTP header that points to a newly created resource — holds the path of the new subscription (its /webhooks/{id}). Use it to fetch or manage what you just created.

For the end-to-end flow — subscribing, delivery guarantees and verifying — see the Webhooks guide.

Request body​

FieldTypeRequiredDescription
namestringyesRequired, non-empty. Max 255 characters.
descriptionstringnoAn optional longer note about the subscription, for your own reference.
urlstringyesRequired. Must use http or https and include a host. Max 1024 characters.
typeAccountRealTimeCalls | AccountEndedCalls | UserEndedCalls | AccountSMS | AccountAITranscriptionyesThe event a subscription fires on. Fetch the live list from GET /webhooks/types.
enabledbooleannoDefaults 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.

FieldTypeDescription
idintegerThe subscription's id.
namestringA label for the subscription, for your own reference.
descriptionstringA longer note about the subscription, for your own reference.
urlstringWhere events are delivered. http or https, max 1024 characters.
typeAccountRealTimeCalls | AccountEndedCalls | UserEndedCalls | AccountSMS | AccountAITranscriptionThe event a subscription fires on. Fetch the live list from GET /webhooks/types.
enabledbooleanWhether events are being delivered.
createdAtstring (RFC 3339)When the subscription was created, RFC 3339 UTC.
updatedAtstring (RFC 3339)When the subscription was last changed, RFC 3339 UTC.

Errors​

StatusMeaning
400invalid_request — a missing or malformed field, an unknown enum value, or an unknown field in the body. Nothing was charged.
401unauthenticated — no credential, or one that is invalid, revoked or expired. The WWW-Authenticate header names the scope the endpoint wanted.
403Two different failures share this status; the type field tells them apart — insufficient_scope (the credential lacks the scope) or permission_denied (the scope is fine, but the user's role lacks the permission).
500internal_error — something failed on our side, not with your request. Safe to retry.

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 →