Webhooks

Introduction

Webhooks in the Telgorithm API serve as a crucial mechanism for real-time communication between Telgorithm's services and external systems. They enable developers to receive instant notifications about specific events, eliminating the need for continuous polling, and facilitating seamless integration with Telgorithm's messaging services.

Webhooks act as triggers, delivering HTTP POST requests to a specified URL endpoint whenever predefined events occur within Telgorithm's ecosystem. Extensive retry policies ensure reliable delivery.

Events Notified via Webhooks

Below is the list of the events along with their brief description. Please refer to the Webhook Samples section for more information.

1. Outbound Message Delivery Status: Updates on the delivery status of outbound messages, including statuses such as
   Sent
   ,
   Delivered
   ,
   Failed
   .
2. Inbound Message: Notifies when a new message is received by the Telgorithm platform.
3. Opt-in/Opt-out: Notifications regarding users opting in or out of receiving messages for a particular TCR Campaign/Use Case, ensuring compliance with regulatory requirements.
4. Inbound Call Initiation: Signals the initiation of an inbound call to a Telgorithm number, enabling immediate response and call handling.
5. Phone Number Status: Indicates changes in the status of phone numbers associated with Telgorithm's services, such as activation, deactivation, or campaign association.
6. Call Status: Provides updates on the status of initiated calls, including call initiation, connection, termination, and any relevant call events.
7. TCR Campaign Imported: Notifies when a sharing request was approved by the Telgorithm platform for a TCR Campaign shared with Telgorithm.

Messaging Config Webhooks vs Company-wide Webhooks

Messaging Config Webhooks

These webhooks are directly related to Messaging Configs set up by the user. They are triggered based on the Inbound/Outbound Messages sent to/from the Phone Numbers associated with these configurations. The URLs to which these webhooks are sent are provided by the user during the setup of the Messaging Config.

The following events are notified via the Messaging Config Webhooks:

1. Outbound Message Delivery Status
2. Inbound Message
3. Opt-in/Opt-out

For each of the above events, a separate webhook URL must be specified in a Messaging Config. If the URL is not set for a particular event type, the webhooks for that event type will not be sent for the Messaging Config.

For more information, please refer to the Messaging Config API documentation.

Overriding Delivery Status Webhook URL per Outbound Message

The Send Outbound Message endpoint allows one to override the Outbound Message Delivery Status Webhook URL for a particular message. The custom webhook URL should be specified in the

request parameter.

Company-wide Webhooks

This group of webhooks is not tied to Messaging Configs. The URLs to which these webhooks are sent are provided by the user via the Webhook Subscriptions API.

The following events are notified via the Company-wide Webhooks:

1. Inbound Call Initiation
2. Phone Number Status
3. Call Status
4. TCR Campaign Imported

Webhook Authentication

An optional

header with the authentication scheme may be included in every Webhook sent by Telgorithm. Use the parameter in Messaging Config or Webhook Subscription to specify the token value.

Note about Webhook URL Overrides

The authorization header token value specified for a Messaging Config remains in effect, even if the Outbound Message Delivery Status Webhook URL has been overridden via the

parameter.

Retry Policies

A Webhook is considered to be successfully delivered if both of the following requirements are satisfied:

• A response to the Webhook request is returned within a timeout of 5 seconds.
• The HTTP status code of the response is in the 2xx range, indicating successful processing.

If a particular Webhook was not successfully delivered, it is scheduled to be retried later with increasing retry intervals spanning 24+ hours in total.

In case there are many consecutive failed requests over a short period of time against a particular URL, that URL may be blocked for some period. During the lockout period, all the Webhook requests destined for that URL will be considered failed without executing the actual request.

After all retry attempts have been exhausted for a particular Webhook, it can be retrieved via the Webhook History API. The API, however, has broad capabilities allowing users to query not only failed Webhooks but also successful ones and those currently being reprocessed.