Webhook Integration Reference

Customers can configure endpoints on their servers to receive webhooks for various events supported by SMS Portal. 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.

NOTE 3: XDateTime variables consider the configurable offset in the API key responsible for the send. The offset is added to these webhooks types at send time.

Variable	Type	GET	POST	Description
`CustomerId`	`string`	✅	✅	An optionally supplied customer ID field.
`EventId`	`long`	✅	✅	The ID provided by the API for the original outgoing SMS batch.
`GroupData`	`json`	❌	✅	All the data pertaining to group sends.
`Id`	`integer`	✅	✅	A unique value for this specific line item.
`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.
`PhoneNumber`	`string`	✅	✅	The mobile number the message was sent to.
`ReceivedDateTime`	`string`	✅	✅	DLR received date/time adjusted by the API key’s SAST offset at send time (SAST = 0 offset), in `dd/MMM/yyyy HH:mm:ss` format.
`ReceivedUtc`	`long`	✅	✅	The UTC UNIX ticks timestamp when the DLR was received.
`SentData`	`string`	❌	✅	The message content sent.
`SentDataPartsCount`	`integer`	✅	✅	The number of message parts for the message content sent.
`SentDataType`	`string`	✅	✅	The data type (`"SMS"` only).
`SentDateTime`	`string`	✅	✅	Mobile network operator submission date/time adjusted by the API key’s SAST offset at send time (SAST = 0 offset), in `dd/MMM/yyyy HH:mm:ss` format.
`SentUtc`	`long`	✅	✅	The UTC UNIX ticks timestamp when the message was submitted to the mobile network operator.
`Status`	`string`	✅	✅	The status that the handset responded with (see Delivery Statuses).

Deprecated Variables

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

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.

NOTE 4: XDateTime variables consider the configurable offset in the API key responsible for the send. The offset is added to these webhooks types at send time.

NOTE 5: SentX variables refer to information on the message sent via SMS Portal. IncomingX variables refer to information on the reply received by SMS Portal.

Variable	Type	GET	POST	Description
`Campaign`	`string`	✅	✅	The campaign that the original message was sent for.
`CustomerId`	`string`	✅	✅	An optionally supplied customer ID field.
`DestinationPhoneNumber`	`string`	✅	✅	The mobile number that received the reply message.
`EventId`	`long`	✅	✅	The ID provided by the API for the original outgoing SMS batch.
`GroupData`	`json`	❌	✅	All the data pertaining to group sends.
`IncomingData`	`string`	❌	✅	The message content received in the reply.
`IncomingDateTime`	`string`	✅	✅	Customer reply received date/time adjusted by the API key’s SAST offset at send time (SAST = 0 offset), in `dd/MMM/yyyy HH:mm:ss` format.
`IncomingId`	`integer`	✅	✅	A unique value for this specific line item.
`IncomingUtc`	`long`	✅	✅	The UTC UNIX ticks timestamp when the message was received.
`OptOut`	`boolean`	✅	✅	A boolean flag indicating whether an opt out was detected (true) or not (false).
`OptOutPhrase`	`string`	✅	✅	Any opt-out phrase detected in the reply (eg. "stop", "opt-out", etc).
`SentData`	`string`	❌	✅	The message content sent.
`SentDateTime`	`string`	✅	✅	Mobile network operator submission date/time adjusted by the API key’s SAST offset at send time (SAST = 0 offset), in `dd/MMM/yyyy HH:mm:ss` format.
`SentId`	`long`	✅	✅	A unique value for this specific outgoing line item.
`SentUtc`	`long`	✅	✅	The UTC UNIX ticks timestamp when the message was submitted to the mobile network operator.
`SourcePhoneNumber`	`string`	✅	✅	The mobile number that sent the reply message.

Deprecated Variables

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

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.
`IncomingDateTime`	`string`	✅	✅	The date and time in SAST when the message was received (`dd/MMM/yyyy HH:mm:ss`).
`IncomingUtc`	`long`	✅	✅	The UTC UNIX ticks timestamp when the message was received.
`Keyword`	`string`	✅	✅	The matched keyword.
`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.
`PhoneNumber`	`string`	✅	✅	The mobile number that sent the message.
`Sc`	`string`	✅	✅	The short code.

Deprecated Variables

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

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

Deprecated Variables

Variable	Type	GET	POST	Rather Use
`CustomerRef`	string	✅	✅	`CustomerId`
`LandingPageName`	string	✅	✅	—
`LandingPageVersion`	string	✅	✅	—
`MsgNumTo`	string	✅	✅	`PhoneNumber`
`SentID`	long	✅	✅	—
`SmppId`	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
`CustomerId`	`string`	✅	✅	An optionally supplied customer ID field.
`InteractionDateTime`	`string`	✅	✅	The date and time in SAST when the link was interacted with (`dd/MMM/yyyy HH:mm:ss`).
`InteractionUtc`	`long`	✅	✅	The UTC UNIX ticks timestamp when the link was interacted with.
`LandingPageComponentId`	`string`	✅	✅	The ID of the component on the landing page that triggered the webhook.
`LandingPageName`	`string`	✅	✅	The name of the landing page.
`LandingPageVersion`	`string`	✅	✅	The version of the landing page.
`PhoneNumber`	`string`	✅	✅	The mobile number the message was sent to.
`Type`	`string`	✅	✅	This will either be `"REDIRECT"`, `"PREVIEW"`, `"AUTHENTICATION"` or `"CONTENT"`, depending on how the user interacted with the landing page.

Deprecated Variables

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