> ## 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.

# Event Webhooks

> Send Telzino events to your CRM, billing or support systems

Event webhooks POST a JSON message to a URL you choose whenever something happens in Telzino — for example an account creates its first agent, or one of your webhook endpoints is disabled.

> [!NOTE]
>
> These are different from **agent webhooks** ([Webhooks](https://docs.telzino.com/functions/webhooks.md)), which an agent calls during a conversation. Event webhooks report platform events and are configured per account, reseller or organization.

## Levels

An endpoint belongs to one level and receives that level's events:

| Endpoint level | Receives | Managed by |
| - | - | - |
| Account | Events of your account; with **Also receive events from the resellers and organizations below this level** on, also every reseller's and organization's | Account admins, account API keys |
| Reseller | Events of that reseller; with the option on, also its organizations' | Account admins, Reseller Admins, reseller or account API keys |
| Organization | Events of that organization and its agents | Account admins, Reseller Admins of its reseller, any API key that can reach it |

An endpoint never receives events from a parent or a sibling: a reseller endpoint never sees another reseller's events, or account-level events.

## Set up

[How to set up Event Webhooks in the Telzino dashboard](https://www.youtube-nocookie.com/embed/iG7EPCN7Ccc)

1. **Dashboard:** Account Settings › **Event Webhooks** (resellers: Reseller › **Event Webhooks**) › **Add endpoint**. **API:** `POST /v1/webhooks` ([reference](https://docs.telzino.com/api-reference/event-webhooks/create.md)).
2. Choose the level, the URL (`https://`, public host), the events, the [payload format](https://docs.telzino.com/event-webhooks/payloads.md) and the [authentication](https://docs.telzino.com/event-webhooks/verifying.md).
3. Optionally fill in the other fields on the form:
   * **Also receive events from the resellers and organizations below this level** appears only for account and reseller endpoints. Organizations have no levels below them, so the checkbox isn't shown at organization level.
   * **Skip events from test accounts** is off by default. Turn it on to leave out events from test accounts.
   * **Email when this endpoint fails** sets the address that is notified when deliveries to this endpoint fail.
   * **Secret (optional)**: leave it empty and Telzino generates one.
4. Copy the secret from **Copy your webhook secret**. It is shown **once**.
5. **Send test** to check your receiver, then watch the **Deliveries** log.

> [!WARNING]
>
> An endpoint's **Level** and **Authentication** can't be changed after it is created. To change either, create a new endpoint and delete the old one.

Event webhooks are enabled per account. If you do not see the page, ask your Telzino account admin to enable it.

## What your receiver must do

* Answer `2xx` within 10 seconds. Anything else is retried ([delivery](https://docs.telzino.com/event-webhooks/delivery.md)).
* Verify the signature or shared secret before trusting a message.
* De-duplicate on `event_id`: a retry or replay sends the same event again.
* Order by `occurred_at`, not arrival time.

## Access errors

An endpoint or delivery outside your account or API key's scope is reported as `404` (its existence is not revealed). Creating an endpoint with an explicit scope outside your API key returns `403` with `forbidden_scope`. For accounts without the feature, the endpoint and delivery routes return `403` with `feature_locked`; `GET /v1/webhook-event-types` is not gated.


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