curl -X POST "https://api.telzino.com/v1/webhooks" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "CRM",
"url": "https://crm.example.com/telzino",
"scope": {
"type": "reseller",
"id": "b2c3…"
},
"event_types": [
"webhook.disabled"
]
}'
const response = await fetch('https://api.telzino.com/v1/webhooks', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"name": "CRM",
"url": "https://crm.example.com/telzino",
"scope": {
"type": "reseller",
"id": "b2c3…"
},
"event_types": [
"webhook.disabled"
]
})
});
import requests
response = requests.post(
'https://api.telzino.com/v1/webhooks',
headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'},
json={
"name": "CRM",
"url": "https://crm.example.com/telzino",
"scope": {
"type": "reseller",
"id": "b2c3…"
},
"event_types": [
"webhook.disabled"
]
}
)
{
"id": "e1f2…", "name": "CRM", "url": "https://crm.example.com/telzino", "enabled": true,
"scope": { "type": "reseller", "id": "b2c3…", "name": "West Coast" },
"include_descendants": true, "event_types": ["webhook.disabled"], "event_settings": {}, "payload_format": "nested", "api_version": "1",
"auth": { "mode": "hmac", "header_name": "X-Telzino-Secret" },
"exclude_test_accounts": false, "notify_email": null,
"health": { "state": "healthy", "failing_since": null, "last_success_at": null, "disabled_at": null, "disabled_reason": null, "held_deliveries": 0 },
"secret_rotation": { "previous_secret_expires_at": null, "next_secret_active_at": null },
"created_at": "2026-10-13T09:00:00Z", "updated_at": "2026-10-13T09:00:00Z", "created_by": "api_key:abc123",
"secret": "whsec_…" }
{ "error": "feature_locked", "error_description": "Event webhooks are not enabled for this account. Contact Telzino to turn them on." }
{ "error": "forbidden_scope", "error_description": "You cannot manage webhooks for that account, reseller or organization." }
{ "error": "invalid_request", "error_description": "Invalid request body",
"details": [ { "code": "invalid_type", "expected": "string", "received": "undefined", "path": ["name"], "message": "Required" } ] }
Event Webhooks
Create Event Webhook
Register an endpoint that receives Telzino events
POST
/
v1
/
webhooks
curl -X POST "https://api.telzino.com/v1/webhooks" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "CRM",
"url": "https://crm.example.com/telzino",
"scope": {
"type": "reseller",
"id": "b2c3…"
},
"event_types": [
"webhook.disabled"
]
}'
const response = await fetch('https://api.telzino.com/v1/webhooks', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"name": "CRM",
"url": "https://crm.example.com/telzino",
"scope": {
"type": "reseller",
"id": "b2c3…"
},
"event_types": [
"webhook.disabled"
]
})
});
import requests
response = requests.post(
'https://api.telzino.com/v1/webhooks',
headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'},
json={
"name": "CRM",
"url": "https://crm.example.com/telzino",
"scope": {
"type": "reseller",
"id": "b2c3…"
},
"event_types": [
"webhook.disabled"
]
}
)
{
"id": "e1f2…", "name": "CRM", "url": "https://crm.example.com/telzino", "enabled": true,
"scope": { "type": "reseller", "id": "b2c3…", "name": "West Coast" },
"include_descendants": true, "event_types": ["webhook.disabled"], "event_settings": {}, "payload_format": "nested", "api_version": "1",
"auth": { "mode": "hmac", "header_name": "X-Telzino-Secret" },
"exclude_test_accounts": false, "notify_email": null,
"health": { "state": "healthy", "failing_since": null, "last_success_at": null, "disabled_at": null, "disabled_reason": null, "held_deliveries": 0 },
"secret_rotation": { "previous_secret_expires_at": null, "next_secret_active_at": null },
"created_at": "2026-10-13T09:00:00Z", "updated_at": "2026-10-13T09:00:00Z", "created_by": "api_key:abc123",
"secret": "whsec_…" }
{ "error": "feature_locked", "error_description": "Event webhooks are not enabled for this account. Contact Telzino to turn them on." }
{ "error": "forbidden_scope", "error_description": "You cannot manage webhooks for that account, reseller or organization." }
{ "error": "invalid_request", "error_description": "Invalid request body",
"details": [ { "code": "invalid_type", "expected": "string", "received": "undefined", "path": ["name"], "message": "Required" } ] }
Request Body
{ "type": "account" | "reseller" | "organization", "id": "<uuid>" } — must be within your API key’s scope.Settings for monitoring events, keyed by event type. Required for each subscribed event that has settings; there are no defaults.
{ "mode": "hmac" | "shared_secret", "header_name"?: string, "secret"?: string }. Default HMAC with a generated secret. secret is optional and generated when omitted.A header name may use only letters, digits and hyphens (64 characters at most), and cannot be a reserved name:
Host, Content-Length, Content-Type, Transfer-Encoding, Connection, User-Agent (any case), or any X-Telzino-* name other than X-Telzino-Secret. A reserved name returns 400 invalid_request with "<name> is a reserved header name; choose another one.".The
secret in the response is shown only once.400 invalid_request responses (error_description in quotes):
- Invalid URL, not
https, with credentials, or a private/loopback/link-local host: “Webhook URL is not a valid URL”, “Webhook URL must use HTTPS”, “Webhook URL must not contain credentials”, “Webhook URL must point at a public host, not a private, loopback or link-local address”. - Unknown or level-disallowed event: “These events are not available at the reseller level: foo.bar.” (the level is named as stored:
partnerfor an account,reseller, ororgfor an organization). - Endpoint limit reached: “This level already has the maximum of N endpoints.”
- Bad supplied
auth.secret: “A secret must be 16-256 printable characters with no spaces.” event_settingsmissing a required setting, out of range, or with an unknown event type or setting name: the message names the event and setting.
A
scope outside what your API key can manage returns 403 with forbidden_scope.curl -X POST "https://api.telzino.com/v1/webhooks" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "CRM",
"url": "https://crm.example.com/telzino",
"scope": {
"type": "reseller",
"id": "b2c3…"
},
"event_types": [
"webhook.disabled"
]
}'
const response = await fetch('https://api.telzino.com/v1/webhooks', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"name": "CRM",
"url": "https://crm.example.com/telzino",
"scope": {
"type": "reseller",
"id": "b2c3…"
},
"event_types": [
"webhook.disabled"
]
})
});
import requests
response = requests.post(
'https://api.telzino.com/v1/webhooks',
headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'},
json={
"name": "CRM",
"url": "https://crm.example.com/telzino",
"scope": {
"type": "reseller",
"id": "b2c3…"
},
"event_types": [
"webhook.disabled"
]
}
)
{
"id": "e1f2…", "name": "CRM", "url": "https://crm.example.com/telzino", "enabled": true,
"scope": { "type": "reseller", "id": "b2c3…", "name": "West Coast" },
"include_descendants": true, "event_types": ["webhook.disabled"], "event_settings": {}, "payload_format": "nested", "api_version": "1",
"auth": { "mode": "hmac", "header_name": "X-Telzino-Secret" },
"exclude_test_accounts": false, "notify_email": null,
"health": { "state": "healthy", "failing_since": null, "last_success_at": null, "disabled_at": null, "disabled_reason": null, "held_deliveries": 0 },
"secret_rotation": { "previous_secret_expires_at": null, "next_secret_active_at": null },
"created_at": "2026-10-13T09:00:00Z", "updated_at": "2026-10-13T09:00:00Z", "created_by": "api_key:abc123",
"secret": "whsec_…" }
{ "error": "feature_locked", "error_description": "Event webhooks are not enabled for this account. Contact Telzino to turn them on." }
{ "error": "forbidden_scope", "error_description": "You cannot manage webhooks for that account, reseller or organization." }
{ "error": "invalid_request", "error_description": "Invalid request body",
"details": [ { "code": "invalid_type", "expected": "string", "received": "undefined", "path": ["name"], "message": "Required" } ] }
