Skip to main content
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.
These are different from agent webhooks (Webhooks), 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: 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

  1. Dashboard: Account Settings › Event Webhooks (resellers: Reseller › Event Webhooks) › Add endpoint. API: POST /v1/webhooks (reference).
  2. Choose the level, the URL (https://, public host), the events, the payload format and the authentication.
  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.
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).
  • 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.