Inbound Message Webhooks

Inbound Message webhooks requests are sent to your endpoints when you:

• Receive a reply to a Shared Sender ID
• Receive any inbound message to an Owned Sender ID

An Inbound Message webhook request will be made to the endpoint specified against the account assigned to sender ID, immediately after the inbound message is sent.

Inbound Message webhook requests will also be signed if a signature secret is assigned to the account.

Request

In this example, the URL supplied against the account is:

https://my-website.com/inbound-msg

Endpoint

A POST request will be made to your endpoint

POST https://my-website.com/inbound-msg

Headers

Key	Description	Example
signature	The computed HMAC-SHA256 request signature. Only provided if the request is signed
timestamp	Epoch timestamp that this request was sent at. Only provided if the request is signed
environment	Environment that this request originated from. Only provided if the request is signed

Body

A reply to an outbound

// This data includes the `batch_uuid` and `message_uuid` of the
// message that has been replied to
{
    "account_uuid": "425a3859-5a87-4742-afa7-7af6b46e5ffb",
    "batch_uuid": "31ba0a09-2f64-4279-bf44-e85b5727a897",
    "message_uuid": "e5f144b9-4ecf-4f43-94b3-4eefca605225",
    "mo_uuid": "3c9615ef-ff68-4073-b88a-303ce1cd8402",
    "channel": "sms",
    "message": "This is an inbound message",
    "at": "2026-01-01T09:30:00.000Z",
    "from": 441234567890,
    "to": "449999999999"
}

Inbound with no existing communication

// This data does not include the `batch_uuid` and `message_uuid`
// as there was no outbound message to reply to
{
    "account_uuid": "425a3859-5a87-4742-afa7-7af6b46e5ffb",
    "batch_uuid": null,
    "message_uuid": null,
    "mo_uuid": "3c9615ef-ff68-4073-b88a-303ce1cd8402",
    "channel": "sms",
    "message": "This is an inbound message",
    "at": "2026-01-01T09:30:00.000Z",
    "from": 441234567890,
    "to": "449999999999"
}

Key	Expected value	Description
account_uuid	string	Account UUID this inbound belongs to
batch_uuid	string|null	Batch UUID of the message being replied to. null if the inbound is not replying to a message
message_uuid	string|null	Message UUID of the message being replied to. null if the inbound is not replying to a message
mo_uuid	string	MO UUID of the inbound. MO (Mobile originated) is a term for messages originating from a mobile handset. This is a unique ID identifying this inbound message
channel	string	The message channel this message was received via
message	string	Content of the inbound message
at	string	ISO 8601 timestamp of when this message was received to our platform
from	integer	The E.164 formatted mobile number that this inbound message was sent from. Mobile number of the message sender
to	string	Sender ID that this inbound message was sent to

Response

Messaging Plus expects a 200 response to the webhook. If a non-200 response is supplied, it will retry up to 5 times.

Verifying request signature

If a signature secret has been specified against the account, we will add a request signature to every request sent to that account.

Verification

To verify a request from us, you'll need to generate a HMAC hash according to the method we provide, then validate that that hash is identical to the one we provide as part of the request.

If the hashes do not match, it's likely that either you've hashed incorrectly, or the request did not originate from us.

Signing process

To generate a signature hash, you'll need to take the headers environment and timestamp from the request.

The signature is constructed as follows:

• Minify the body JSON, and base64 encode it
• Combine the base64-body , environment, and timestamp into a single string. Delimited by full stops/periods (.)
• Run the combined string through a HMAC SHA256 function, using the key you originally provided us as the signing key. The output format should be base64

The string signature you generate can then be compared against the signature header in the request.

Code example

// Minify the body JSON, and base64 encode it
let b64_body = base64_encode(json_minify(body));

// Combine the `base64-body` , `environment`, and `timestamp` into a
// single string. Delimited by full stops/periods (`.`) 
let hash_input = format!("{b64_body}.{env}.{timestamp}");

// Run the combined string through a HMAC SHA256 function, using the
// key you originally provided us as the signing key. The output format
// should be base64
let hash = hmac_sha256(hash_input, secret_key, HmacOutput::Base64);