> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telzino.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Event Webhook

> Register an endpoint that receives Telzino events

## Request Body

**name** `string` *required*

Up to 100 characters.

**url** `string` *required*

`https` URL on a public host.

**scope** `object` *required*

`{ "type": "account" | "reseller" | "organization", "id": "<uuid>" }` — must be within your API key's scope.

**event\_types** `string[]` *required*

Events available at that level (`GET /v1/webhook-event-types`).

**event\_settings** `object`

Settings for [monitoring events](https://docs.telzino.com/event-webhooks/events.md#event-settings), keyed by event type. Required for each subscribed event that has settings; there are no defaults.

**include\_descendants** `boolean` (default: true)

Also receive events from the levels below.

**payload\_format** `string` (default: nested)

`nested` or `flat`.

**auth** `object`

`{ "mode": "hmac" | "shared_secret", "header_name"?: string, "secret"?: string }`. Default HMAC with a generated secret. `secret` is optional and generated when omitted.

**exclude\_test\_accounts** `boolean` (default: false)

Skip events from Telzino test accounts.

**notify\_email** `string`

Who is emailed when the endpoint fails.

> [!NOTE]
>
> 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."`.

> [!WARNING]
>
> The `secret` in the response is shown only once.

Other `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: `partner` for an account, `reseller`, or `org` for 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_settings` missing a required setting, out of range, or with an unknown event type or setting name: the message names the event and setting.

> [!NOTE]
>
> A `scope` outside what your API key can manage returns `403` with `forbidden_scope`.

```bash cURL theme={null}
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"
  ]
}'
```

```javascript JavaScript theme={null}
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"
    ]
  })
});
```

```python Python theme={null}
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"
      ]
    }
)
```

```json 201 theme={null}
{
  "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_…" }
```

```json 403 theme={null}
{ "error": "feature_locked", "error_description": "Event webhooks are not enabled for this account. Contact Telzino to turn them on." }
```

```json 403 theme={null}
{ "error": "forbidden_scope", "error_description": "You cannot manage webhooks for that account, reseller or organization." }
```

```json 400 theme={null}
{ "error": "invalid_request", "error_description": "Invalid request body",
  "details": [ { "code": "invalid_type", "expected": "string", "received": "undefined", "path": ["name"], "message": "Required" } ] }
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.