Templates and Property Substitution
Templates and Property Substitution
Customers can configure endpoints on their servers to receive webhooks for various events that are supported. We substitutes data into webhook fully configurable webhook requests through a mechanism whereby a customer configures a template in our portal and when the webhook is ready to be dispatched from our system the applicable variables are injected into the customer's template.
NOTE 1: The term"property" or "variable" is used interchangeably.
Property Notation and Types
We use a similar @@
notation to our sending pages for adding properties in webhooks (eg. @@SentId@@
).
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 2 *: The
json
property refers to a nested object and is only applicable to HTTP POST requests.
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.
Customers are responsible for ensuring that valid query parameters are being built in HTTP GET
webhooks and/or that valid JSON is being built in HTTP POST
webhook requests (eg. not substituting a string without "", etc.). Our portal tooling does assist with this validation.
Example HTTP GET Substitution
URL Template:
https://www.your-example-domain.com?type=@@Type@@&customerRef=@@CustomerRef@@&msgNumTo=@@MsgNumTo@@&landingPageVersion=@@LandingPageVersion@@&landingPageName=@@LandingPageName@@
Resolved URL (after property substitution):
https://www.your-example-domain.com?type=REDIRECT&customerRef=your_optional_reference_id&msgNumTo=27000000001&landingPageVersion=Version1&landingPageName=ExampleLandingTemplate
Example HTTP POST Substitution
Request Body Template:
{
"phoneNumber": "@@PhoneNumber@@",
"customerId": "@@CustomerId@@",
"type": "@@Type@@",
"interactionUtc": @@InteractionUtc@@,
"landingPageName": "@@LandingPageName@@",
"landingPageVersion": "@@LandingPageVersion@@",
"landingPageComponentId": "@@LandingPageComponentId@@"
}
Resolved Request Body (after property substitution)
{
"phoneNumber": "27000000001",
"customerId": "your_optional_reference_id",
"type": "REDIRECT",
"interactionUtc": 1735718400,
"landingPageName": "ExampleLandingTemplate",
"landingPageVersion": "Version1",
"landingPageComponentId": "button_77"
}
Truncation
To align with the URL and JSON body length limitations (discussed later), we do apply truncation to the SentData
, NumberValue1
, and IncomingData
properties applicable to the SMS Delivery Receipt and SMS Reply webhooks.
If a value is truncated, it will end with ...
Limitations are imposed as follows:
SentData
is limited to 157 characters (160 incl....
).NumberValue1
is limited to 157 characters (160 incl....
).IncomingData
is limited to 477 characters (480 incl....
).
***NOTE 3 *: Should customers require the full data for these fields they can use the reporting functionality in the customer portal.
Default Templates
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 from.
Backwards Compatibility
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.
Updated 4 days ago