Webhooks

Webhooks are how we notify your systems about events in real time, instead of you polling our API for updates. When something happens, like a message being delivered or a call ringing, we send an HTTP POST request to a URL you specify. We apply extensive retry policies so you can rely on webhooks for delivery, even through brief outages on your end.

Events we notify

• Outbound message delivery status: updates as an outbound message moves through Sent, Delivered, or Failed

• Inbound message: a new message arrives on your account

• Opt-in/opt-out: a recipient opts in or out for a TCR Campaign or Use Case

• Inbound call initiation: an inbound call reaches one of your numbers

• Phone number status: a phone number changes state, such as activation, deactivation, or campaign association

• Call status: a call's status changes, including connection and termination

• TCR Campaign imported: a sharing request for a TCR Campaign shared with Telgorithm is approved

See Webhook Samples for full payload examples of each event.

Messaging Config webhooks vs. company-wide webhooks

Messaging Config webhooks

These webhooks are tied to the Messaging Configs you set up. They fire based on inbound and outbound messages sent to or from the phone numbers attached to that configuration, and go to the URL you provided when you set up the Messaging Config.

Three event types are sent this way:

1. Outbound message delivery status

2. Inbound message

3. Opt-in/opt-out

Each event type needs its own webhook URL on the Messaging Config. If you leave a URL unset, we won't send webhooks for that event type on that config. See the Messaging Config API documentation for setup details.

Overriding the delivery status webhook URL

You can override the outbound message delivery status webhook URL for a single message. Set the callbackUrlOverride parameter on the Send Outbound Message request.

Company-wide webhooks

These aren't tied to a Messaging Config. You provide their URLs through the Webhook Subscriptions API instead.

Four event types are sent this way:

1. Inbound call initiation

2. Phone number status

3. Call status

4. TCR Campaign imported

Webhook authentication

Every webhook we send can include an Authorization header using the Bearer scheme. Set the token with the authorizationBearer parameter on the Messaging Config or Webhook Subscription.

Retry policy

We count a webhook as delivered when both of these are true:

• Your endpoint responds within 5 seconds

• The response status code is in the 2xx range

If delivery fails, we retry with increasing intervals across more than 24 hours in total. If a URL fails many times in a row over a short window, we may temporarily block it. While blocked, webhooks to that URL are marked failed without us attempting the request.

Once retries are exhausted, you can look up the webhook's history, including successful and in-progress ones, through the Webhook History API.