Webhook Integration

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.

VariableTypeGETPOSTDescription
CustomerIdstringAn optionally supplied customer ID field.
EventIdlongThe ID provided by the API for the original outgoing SMS batch.
GroupDatajsonAll the data pertaining to group sends.
IdintegerA unique value for this specific line item.
MccintegerThe Mobile Country Code (MCC) is the country where the mobile number is registered.
MncstringThe Mobile Network Code (MNC) is used to identify a mobile network within a country.
PhoneNumberstringThe mobile number the message was sent to.
ReceivedDateTimestringThe date and time in SAST when the DLR was received (dd/MMM/yyyy HH:mm:ss).
ReceivedUtclongThe UTC UNIX ticks timestamp when the DLR was received.
SentDatastringThe message content sent.
SentDataPartsCountintegerThe number of message parts for the message content sent.
SentDataTypestringThe data type ("SMS" only).
SentDateTimestringThe date and time in SAST when the message was submitted to the mobile network operator (dd/MMM/yyyy HH:mm:ss).
SentUtclongThe UTC UNIX ticks timestamp when the message was submitted to the mobile network operator.
StatusstringThe status that the handset responded with (see Delivery Statuses).

Deprecated Variables

VariableTypeGETPOSTRather Use
CustomerIDstringCustomerId
DatastringSentData
DataTypestringSentDataType
DestinationstringPhoneNumber
EventIDlongEventId
GRPDescstringGroupData
GRPNamestringGroupData
IDintegerId
MsgCountintegerSentDataPartsCount
MsisdnstringPhoneNumber
NumberValue1stringGroupData
NumberValue2stringGroupData
NumberValue3stringGroupData
NumberValue4stringGroupData
NumberValue5stringGroupData
NumberValue6stringGroupData
PhonenumberstringPhoneNumber
ReceivedlongReceivedUtc
SentDataTimestringSentDateTime
UserReferencestringCustomerId

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.

VariableTypeGETPOSTDescription
CampaignstringThe campaign that the original message was sent for.
CustomerIdstringAn optionally supplied customer ID field.
DestinationPhoneNumberstringThe mobile number that received the reply message.
EventIdlongThe ID provided by the API for the original outgoing SMS batch.
GroupDatajsonAll the data pertaining to group sends.
IncomingDatastringThe message content received in the reply.
IncomingDateTimestringThe date and time in SAST when the message was received (dd/MMM/yyyy HH:mm:ss).
IncomingIdintegerA unique value for this specific line item.
IncomingUtclongThe UTC UNIX ticks timestamp when the message was received.
SentDatastringThe message content sent.
SentDateTimestringThe date and time in SAST when the message was submitted to the mobile network operator (dd/MMM/yyyy HH:mm:ss).
SentIdlongA unique value for this specific outgoing line item.
SentUtclongThe UTC UNIX ticks timestamp when the message was submitted to the mobile network operator.
SourcePhoneNumberstringThe mobile number that sent the reply message.

Deprecated Variables

VariableTypeGETPOSTRather Use
CustomerIDstringCustomerId
EventIDlongEventId
IdintegerIncomingId
IncomingDataTimestringIncomingDateTime
IncomingIDintegerIncomingId
MessagestringIncomingData
MsisdnstringSourcePhoneNumber
NumberValue1stringGroupData
NumberValue2stringGroupData
NumberValue3stringGroupData
NumberValue4stringGroupData
NumberValue5stringGroupData
NumberValue6stringGroupData
PhonenumberstringSourcePhoneNumber
ReceivedlongIncomingUtc
SentDataTimestringSentDateTime
SentIDlongSentId
SentMessageGRPDescstringGroupData
SentMessageGRPNamestringGroupData
TolongDestinationPhoneNumber
UserReferencestringCustomerId

3. Short Code Interactions

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

VariableTypeGETPOSTDescription
IdintegerThe short code message ID.
IncomingDatastringThe message content received in the reply.
IncomingDateTimestringThe date and time in SAST when the message was received (dd/MMM/yyyy HH:mm:ss).
IncomingUtclongThe UTC UNIX ticks timestamp when the message was received.
KeywordstringThe matched keyword.
MccintegerThe Mobile Country Code (MCC) is the country where the mobile number is registered.
MncstringThe Mobile Network Code (MNC) is used to identify a mobile network within a country.
PhoneNumberstringThe mobile number that sent the message.
ScstringThe short code.

Deprecated Variables

VariableTypeGETPOSTRather Use
IDintegerId
MessagestringIncomingData
MobilestringPhoneNumber
SCstringSc

4. Short URL Events

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

VariableTypeGETPOSTDescription
CustomerIdstringAn optionally supplied customer ID field.
InteractionDateTimestringThe date and time in SAST when the link was interacted with (dd/MMM/yyyy HH:mm:ss).
InteractionUtclongThe UTC UNIX ticks timestamp when the link was interacted with.
PhoneNumberstringThe mobile number the message was sent to.
TypestringThis will either be "REDIRECT" or "PREVIEW", depending on whether the URL was clicked or previewed.

Deprecated Variables

VariableTypeGETPOSTRather Use
CustomerRefstringCustomerId
LandingPageNamestring
LandingPageVersionstring
MsgNumTostringPhoneNumber
SentIDlong
SmppIdstring

5. Landing Page Events

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

VariableTypeGETPOSTDescription
CustomerIdstringAn optionally supplied customer ID field.
InteractionDateTimestringThe date and time in SAST when the link was interacted with (dd/MMM/yyyy HH:mm:ss).
InteractionUtclongThe UTC UNIX ticks timestamp when the link was interacted with.
LandingPageComponentIdstringThe ID of the component on the landing page that triggered the webhook.
LandingPageNamestringThe name of the landing page.
LandingPageVersionstringThe version of the landing page.
PhoneNumberstringThe mobile number the message was sent to.
TypestringThis will either be "REDIRECT", "PREVIEW", "AUTHENTICATION" or "CONTENT", depending on how the user interacted with the landing page.

Deprecated Variables

VariableTypeGETPOSTRather Use
CustomerRefstringCustomerId
MsgNumTostringPhoneNumber