Webhook Integration Reference

Customers can configure endpoints on their servers to receive webhooks for various events. Below is a complete breakdown of the webhook features and functionality as well as the five supported webhook types and the data available with each webhook type.

Webhook Core Functionality

Webhook integration only supports HTTPS endpoints. HTTP is NOT supported.

For further security and/or configurability we allow our customers to put any content in the header of the webhook requests. Provided it does not override some of the required header fields (ie. Content-Length, Content-Type, Host).

Webhooks are viewed as real-time events. Operating in a multi-customer, multi-service provider, high-throughput environment, we do not artificially slow down / batch webhook requests for any customers.

Properties

Data from our system is provided in webhooks through properties/variables (the two terms are used interchangeably).

We use a similar @@ notation to our sending pages for adding properties in webhooks (eg. @@SentId@@).
As will become evident, some properties are only available to certain types of webhooks and further some properties are only available if the webhook is a HTTP POST request.
We maintain backwards compatibility through our legacy/deprecated properties. These should not be used in new webhooks but may still be used in existing webhooks. Existing webhooks won't be affected by the updated properties.
Properties have a type (long, integer, string, json). This is provided so that customers understand how to parse these properties (eg. wrap string properties in quotation marks, etc.).

NOTE: The json property refers to a nested object and is only applicable to HTTP POST requests.
We make default templates available to our customers for each type of webhook. The default template contains all the information that we believe to be essential for that type of webhook. This provides a good starting point for customers to configure their own webhook integrations.

Protocol Support

In terms of protocol support, our webhooks convey information using either a HTTP GET request or a HTTP POST request. Every type of webhook supports either GET/POST. Other HTTP request types (PUT, PATCH, etc.) are not supported. This is discussed in more detail below:

GET Requests

Data is sent in the URL query string.
It is easy to debug/bookmark these webhook types.
The URL length limited to 2024 unicode characters (~2 KB).
This type of webhook is NOT suited for large or sensitive payloads.
Some of the larger properties, such as the full message sent, are not available using the GET request webhook.
NO request body is sent.

POST Requests

Data sent as a JSON-encoded request body, also limited to 2024 unicode characters (~2 KB).
The URL length remains limited at 2024 unicode characters (~2 KB).
Supports large and complex structures (e.g. GroupData).
Preferred format for sensitive fields as they will not be publicly exposed in the unencrypted URL.
Requires JSON parsing capability.
NO properties may be used in the URL of the request.

Webhook Custom Request Body (POST only)

Webhooks using the HTTP POST method now support customizable request bodies. By default, all available variables will be included in the JSON payload. However, if your integration requires a simplified structure, you can remove specific variables via the webhook edit modal in our Control Panel.

To help you configure your integration, a preview of the JSON payload (with example data) is provided within the modal, giving you full visibility into the data structure being sent.

This enhancement gives you greater control and flexibility when consuming our webhooks.

Webhook Types

The following section details the properties available to each webhook type as well as the use-case for the various webhook types. The Variable column indicates what should be put within the @@ encapsulation. The UI will assist with the variable encapsulation process.

NOTE 1: Deprecated variables are listed with a "Rather Use" column that indicates which property should rather be used. If this column is empty, it means that the variable is no longer relevant for that type of webhook.

NOTE 2: Variables are case sensitive. As an example, ID and Id are not the same.

1. SMS Delivery Receipts (DLRs)

Delivery Receipts (DLRs) are webhooks that provide feedback on the delivery of a single SMS.

Variable	Type	GET	POST	Description
`Id`	`integer`	✅	✅	A unique value for this specific line item.
`EventId`	`long`	✅	✅	The ID provided by the API for the original outgoing SMS batch.
`PhoneNumber`	`string`	✅	✅	The mobile number the message was sent to.
`Mcc`	`integer`	✅	✅	The Mobile Country Code (MCC) is the country where the mobile number is registered.
`Mnc`	`string`	✅	✅	The Mobile Network Code (MNC) is used to identify a mobile network within a country.
`SentDataType`	`string`	✅	✅	The data type (`"SMS"` only).
`SentData`	`string`	❌	✅	The message content sent.
`SentDataPartsCount`	`integer`	✅	✅	The number of message parts for the message content sent.
`ReceivedUtc`	`long`	✅	✅	The UTC UNIX ticks timestamp when the DLR was received.
`ReceivedDateTime`	`string`	✅	✅	The local date and time (`dd/MMM/yyyy HH:mm:ss`) for when the DLR was received.
`SentUtc`	`long`	✅	✅	The UTC UNIX ticks timestamp when the message was sent.
`SentDateTime`	`string`	✅	✅	The local date and time (`dd/MMM/yyyy HH:mm:ss`) for when the message was sent.
`Status`	`string`	✅	✅	The status that the handset responded with (see Delivery Statuses.
`CustomerId`	`string`	✅	✅	An optionally supplied customer ID field.
`GroupData`	`json`	❌	✅	All the data pertaining to group sends.

Deprecated Variables

Variable	Type	GET	POST	Rather Use
`Destination`	`string`	✅	✅	`PhoneNumber`
`Received`	`long`	✅	✅	`ReceivedUtc`
`UserReference`	`string`	✅	✅	`CustomerId`
`CustomerID`	`string`	✅	✅	`CustomerId`
`MsgCount`	`integer`	✅	✅	`SentDataPartsCount`
`ID`	`integer`	✅	✅	`Id`
`EventID`	`long`	✅	✅	`EventId`
`Phonenumber`	`string`	✅	✅	`PhoneNumber`
`Msisdn`	`string`	✅	✅	`PhoneNumber`
`DataType`	`string`	✅	✅	`SentDataType`
`Data`	`string`	✅	✅	`SentData`
`SentDataTime`	`string`	✅	✅	`SentDateTime`
`GRPName`	`string`	✅	✅	`GroupData`
`GRPDesc`	`string`	✅	✅	`GroupData`
`NumberValue1`	`string`	✅	✅	`GroupData`
`NumberValue2`	`string`	✅	✅	`GroupData`
`NumberValue3`	`string`	✅	✅	`GroupData`
`NumberValue4`	`string`	✅	✅	`GroupData`
`NumberValue5`	`string`	✅	✅	`GroupData`
`NumberValue6`	`string`	✅	✅	`GroupData`

2. SMS Replies (MOs)

SMS Replies are webhooks that provide feedback on the reply that someone replied with after receiving a single SMS that was sent to them.

Variable	Type	GET	POST	Description
`IncomingId`	`integer`	✅	✅	A unique value for this specific line item.
`EventId`	`long`	✅	✅	The ID provided by the API for the original outgoing SMS batch.
`SourcePhoneNumber`	`string`	✅	✅	The mobile number that sent the reply message.
`DestinationPhoneNumber`	`string`	✅	✅	The mobile number that received the reply message.
`IncomingData`	`string`	❌	✅	The message content received in the reply.
`IncomingUtc`	`long`	✅	✅	The UTC UNIX ticks timestamp when the message was received.
`IncomingDateTime`	`string`	✅	✅	The local date and time (`dd/MMM/yyyy HH:mm:ss`) when the message was received.
`SentId`	`long`	✅	✅	A unique value for this specific outgoing line item.
`SentData`	`string`	❌	✅	The message content sent.
`SentUtc`	`long`	✅	✅	The UTC UNIX ticks timestamp when the message was sent.
`SentDateTime`	`string`	✅	✅	The local date and time (`dd/MMM/yyyy HH:mm:ss`) for when the message was sent.
`CustomerId`	`string`	✅	✅	An optionally supplied customer ID field.
`Campaign`	`string`	✅	✅	The campaign that the original message was sent for.
`GroupData`	`json`	❌	✅	All the data pertaining to group sends.

Deprecated Variables

Variable	Type	GET	POST	Rather Use
`Id`	`integer`	✅	✅	`IncomingId`
`IncomingID`	`integer`	✅	✅	`IncomingId`
`EventID`	`long`	✅	✅	`EventId`
`Msisdn`	`string`	✅	✅	`SourcePhoneNumber`
`Phonenumber`	`string`	✅	✅	`SourcePhoneNumber`
`Message`	`string`	✅	✅	`IncomingData`
`IncomingDataTime`	`string`	✅	✅	`IncomingDateTime`
`To`	`long`	✅	✅	`DestinationPhoneNumber`
`Received`	`long`	✅	✅	`IncomingUtc`
`UserReference`	`string`	✅	✅	`CustomerId`
`SentID`	`long`	✅	✅	`SentId`
`SentDataTime`	`string`	✅	✅	`SentDateTime`
`CustomerID`	`string`	✅	✅	`CustomerId`
`SentMessageGRPName`	`string`	✅	✅	`GroupData`
`SentMessageGRPDesc`	`string`	✅	✅	`GroupData`
`NumberValue1`	`string`	✅	✅	`GroupData`
`NumberValue2`	`string`	✅	✅	`GroupData`
`NumberValue3`	`string`	✅	✅	`GroupData`
`NumberValue4`	`string`	✅	✅	`GroupData`
`NumberValue5`	`string`	✅	✅	`GroupData`
`NumberValue6`	`string`	✅	✅	`GroupData`

3. Short Code Interactions

Short code interactions are webhooks that provide feedback on SMS's sent to short codes.

Variable	Type	GET	POST	Description
`Id`	`integer`	✅	✅	The short code message ID.
`IncomingData`	`string`	❌	✅	The message content received in the reply.
`IncomingUtc`	`long`	✅	✅	The UTC UNIX ticks timestamp when the message was received.
`IncomingDateTime`	`string`	✅	✅	The local date and time (`dd/MMM/yyyy HH:mm:ss`) when the message was received.
`Sc`	`string`	✅	✅	The short code.
`Keyword`	`string`	✅	✅	The matched keyword.
`PhoneNumber`	`string`	✅	✅	The mobile number that sent the message.
`Mcc`	`integer`	✅	✅	The Mobile Country Code (MCC) is the country where the mobile number is registered.
`Mnc`	`string`	✅	✅	The Mobile Network Code (MNC) is used to identify a mobile network within a country.

Deprecated Variables

Variable	Type	GET	POST	Rather Use
`ID`	`integer`	✅	✅	`Id`
`Message`	`string`	✅	✅	`IncomingData`
`SC`	`string`	✅	✅	`Sc`
`Mobile`	`string`	✅	✅	`PhoneNumber`

4. Short URL Events

Short URL events are webhooks that provide feedback on any interactions with short URLs created in our platform.

Variable	Type	GET	POST	Description
`PhoneNumber`	`string`	✅	✅	The mobile number the message was sent to.
`CustomerId`	`string`	✅	✅	An optionally supplied customer ID field.
`Type`	`string`	✅	✅	This will either be `"REDIRECT"` or `"PREVIEW"`, depending on whether the URL was clicked or previewed.
`InteractionUtc`	`long`	✅	✅	The UTC UNIX ticks timestamp when the link was interacted with.
`InteractionDateTime`	`string`	✅	✅	The local date and time (`dd/MMM/yyyy HH:mm:ss`) when the link was interacted with.

Deprecated Variables

Variable	Type	GET	POST	Rather Use
`SentID`	long	✅	✅	—
`MsgNumTo`	string	✅	✅	`PhoneNumber`
`SmppId`	string	✅	✅	—
`CustomerRef`	string	✅	✅	`CustomerId`
`LandingPageName`	string	✅	✅	—
`LandingPageVersion`	string	✅	✅	—

5. Landing Page Events

Landing page events are webhooks that provide feedback on any interactions with landing pages created in our platform.

Variable	Type	GET	POST	Description
`PhoneNumber`	`string`	✅	✅	The mobile number the message was sent to.
`CustomerId`	`string`	✅	✅	An optionally supplied customer ID field.
`Type`	`string`	✅	✅	This will either be `"REDIRECT"`, `"PREVIEW"`, `"AUTHENTICATION"` or `"CONTENT"`, depending on how the user interacted with the landing page.
`LandingPageName`	`string`	✅	✅	The name of the landing page.
`LandingPageVersion`	`string`	✅	✅	The version of the landing page.
`LandingPageComponentId`	`string`	✅	✅	The ID of the component on the landing page that triggered the webhook.
`InteractionUtc`	`long`	✅	✅	The UTC UNIX ticks timestamp when the link was interacted with.
`InteractionDateTime`	`string`	✅	✅	The local date and time (`dd/MMM/yyyy HH:mm:ss`) when the link was interacted with.

Deprecated Variables

Variable	Type	GET	POST	Rather Use
`MsgNumTo`	`string`	✅	✅	`PhoneNumber`
`CustomerRef`	`string`	✅	✅	`CustomerId`