Skip to main content

Verifying authenticity

There's no built-in way to prove a webhook really came from us, so you need other ways to tell a genuine event from a forged one. This page explains the gap and the controls that close it.

Webhook deliveries are not signed

A delivery has no signature of any kind — no HMAC, no shared secret, nothing in the request that proves it came from Telebroad. So anyone who learns your webhook URL can POST a forged event to it.

Until signing ships, these are the controls available.

Treat the URL as a secret​

It is the closest thing to a credential this system has.

  • Make it unguessable — https://example.com/hooks/tb/8f2b1c94d7e34a1f, not https://example.com/telebroad.
  • Rotate it if it leaks: update the subscription's url. Effective immediately, no coordination with us needed.

You can also put your own secret token in the URL and reject any request that lacks it — keep it in the URL path, not the ?query= part, since query strings get recorded in server logs along the way.

Confirm before you act​

A webhook is a hint that something happened; the API is the record of what did.

Never act on money, access, or destructive operations from a webhook alone. First look up the call, message, or recording through the API, using the id in the payload. A forged webhook can claim anything, but it can't change what the API returns — so if the event was fake, the lookup won't confirm it: the id won't exist, or the details won't match.

IP allowlisting​

Deliveries come from Telebroad's outbound IP addresses. Ask support for the current list. Confirm it before relying on it — the list changes with infrastructure work, and an out-of-date allowlist silently blocks every event.

mTLS (client-certificate authentication) is not supported.