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. 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
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Required, non-empty. Max 255 characters. |
description | string | no | An optional longer note about the subscription, for your own reference. |
url | string | yes | Required. Must use http or https and include a host. Max 1024 characters. |
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 | The subscription's id. |
name | string | A label for the subscription, for your own reference. |
description | string | A longer note about the subscription, for your own reference. |
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) | When the subscription was created, RFC 3339 UTC. |
updatedAt | string (RFC 3339) | When the subscription was last changed, RFC 3339 UTC. |
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; 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). |
500 | internal_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}'