Documentation
Log inSign up
Start typing to search…

Templates and Property Substitution

Templates and Property Substitution

Customers can configure endpoints on their servers to receive webhooks for various events supported by SMSPortal.

SMSPortal substitutes data into 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.

Constraints

To receive webhooks, customers are required to set up a template that defines the structure and content of the webhook message they wish to receive.

The following constraints apply to webhook templates:

  • Minimum properties: Templates must contain at least one property. A template without any properties would convey no useful information from the SMSPortal system.
  • GET templates:
    • Must produce a valid HTTP URL after property substitution.
    • The resulting URL must not contain whitespace or invalid URL characters.
    • See RFC 3986, Uniform Resource Identifier (URI): Generic Syntax, for the formal definition of URL structure and encoding requirements.
    • The SMSPortal testing suite can assist customers in validating the generated URLs.
  • POST templates:
    • Must produce a valid JSON body after property substitution.
    • The resulting JSON must comply with RFC 8259, The JavaScript Object Notation (JSON) Data Interchange Format.
    • The SMSPortal testing suite can assist customers in validating their JSON payloads.

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 1: 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 2: Should customers require the full data for these fields they can use the reporting functionality in the customer portal.

Default Templates

SMSPortal provides default webhook templates for each webhook type as a starting point for customers. These templates are designed to include what we consider to be the most essential and practical fields for that specific webhook type.

  • Opinionated design: The default templates reflect SMSPortal’s opinionated view of what is typically required for reliable and meaningful webhook integrations. They do not include every available property. Instead, only including those that are most relevant and non-redundant. For example, a default template will include either SentDateTime or SentUtc (Unix timestamp), but not both, since they represent the same data in different formats.
  • Customizability: Customers can freely use the default template as a starting point to create their own template, including adding/removing properties as needed.
  • Supported request types: Default templates are currently provided only for POST requests. GET request templates must be defined manually by the customer.
  • Purpose: These defaults aim to accelerate integration setup while maintaining clarity, consistency, and compatibility across webhook consumers.

NOTE 3: SMSPortal may update the default templates over time to align with new webhook features or best practices.

NOTE 4: Customers are encouraged to review the available properties list to ensure their template includes all fields necessary for their use case.

Backwards Compatibility

We maintain backwards compatibility through our legacy/deprecated properties.

Deprecated properties 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 2 days ago