Allowed Methods, URLs, and Headers

This page describes the HTTP related constraints imposed when configuring webhooks.

Method Types

Our webhooks convey information using either an HTTP GET or POST method. Other HTTP method types (PUT, PATCH, etc.) are not supported.

Whether you use a HTTP GET or POST method, the webhook template is fully customizable. Along with variable substitution, customers can:

Insert their own constant data into the URL path / query parameters for either HTTP GET or POST webhooks.
Configure their own JSON request body structure and/or insert their own constant data into the JSON request body for HTTP POST webhooks.

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

Specific request method details are discussed in the subsections below.

HTTP GET Requests

Data is conveyed through property substitution in the URL query string.

Example below:

Part	Data
URL	`https://www.your-example-domain.com?type=REDIRECT&customerRef=your_optional_reference_id&msgNumTo=27000000001&landingPageVersion=Version1&landingPageName=ExampleLandingTemplate`
Request Body	`null`

It is easy to debug/bookmark these webhook types as all the data is conveyed in the URL. No request body is sent (Content-Length and Content-Type headers are omitted).

The URL length limited to 2000 UTF8 characters (~2 KB). Because of this, GET webhooks are typically NOT suited for very large payloads.

HTTP POST Requests

Data is conveyed through property substitution in a JSON-encoded request body.

Example below:

Part	Data
URL	`https://www.your-example-domain.com`
Request Body	`{"phoneNumber":"27000000001","customerId":"your_optional_reference_id","type":"REDIRECT","interactionUtc":1735718400,"landingPageName":"ExampleLandingTemplate","landingPageVersion":"Version1","landingPageComponentId":"button_77"}`

Because the data is conveyed in the body of the request and not the URL, these are slightly more challenging to debug and do require JSON parsing capability on the server that will receive the webhook.

Our HTTP client will always set the following HTTP headers for HTTP POST requests:

Header Name	Header Value
`Content-Type`	`application/json; charset=utf-8`
`Content-Length`	Calculated as the character length of the JSON request body. (eg. `229`)

Similar to the GET requests, the URL length remains limited at 2000 UTF8 characters (~2 KB). The JSON request body is limited to 4000 UTF8 characters (~4 KB), making POST requests more suitable for very large/complex payloads.

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

We do not allow property substitution in the URL of a POST webhook request.

URL Constraints

The URL provides the address where the webhook request will be made. For security reasons, we do impose some limitations on the URL.

These limitations are as follows:

The URL has to be HTTPS. HTTP is not supported.
The URL may not contain an IP address.
Domains must resolve to IPv4 addresses. IPv6 is not supported.
The URL must be compliant with the following RFC standards:

Standard	Description
RFC1122	Requirements for Internet hosts at the link, IP, and transport layers (the “communication layers”).
RFC1918	Defines private IPv4 address space for use inside private networks (e.g., enterprise internets).
RFC2544	Benchmarking methodology for network interconnect devices (e.g., throughput, latency, frame loss).
RFC3927	Dynamic configuration of IPv4 link-local addresses in 169.254/16 for same-link communication.
RFC5737	Reserves three IPv4 unicast blocks for documentation and examples (TEST-NET addresses).
RFC5771	IANA guidelines for assigning IPv4 multicast addresses and related allocation categories.
RFC6598	Reserves 100.64.0.0/10 as shared address space for Carrier-Grade NAT (CGN).
RFC6890	Defines and maintains the IANA special-purpose address registries for IPv4/IPv6 (e.g., loopback, link-local).

Headers

We offer the capability for customers to save their own HTTP headers (provided these are not in the forbidden list). This allows customers to set headers required for purposes in their domain (eg. Authorization, etc.).

Constraints

The header must be compliant with HTTP header requirements and must contain a non-white space value.

Default Headers

We set the following default headers:

Header Name	Header Value
`User-Agent`	`SMS Webhook Engine`

Forbidden Headers

The following headers are forbidden for usage from customers:

:authority, :method, :path, :scheme, Accept, Accept-Charset, Accept-Encoding, Accept-Language, Cache-Control, Connection, Content-Disposition, Content-Encoding, Content-Language, Content-Length, Content-Location, Content-MD5, Content-Range, Content-Type, Cookie, Cookie2, Digest, DNT, Expect, Forwarded, Host, http2-settings, Idempotency-Key, If-Match, If-Modified-Since, If-None-Match, If-Range, If-Unmodified-Since, Keep-Alive, Max-Forwards, Origin, Pragma, Proxy-Authenticate, Proxy-Authorization, Proxy-Connection, Range, Referer, Sec-Fetch-Dest, Sec-Fetch-Mode, Sec-Fetch-Site, Set-Cookie, Signature, Signature-Input, TE, Trailer, Transfer-Encoding, Upgrade, Upgrade-Insecure-Requests, User-Agent, Via, X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Proto