Inbound Message Webhooks

To receive your inbound messages, you need to assign a webhook URL endpoint for them to be sent. Messaging Plus will then send a payload upon receiving an inbound message, forwarding it to the endpoint you specify.

Additionally, you can specify a webhook secret. If the secret is specified, we will sign the requests - allowing you to verify that they're originating from Messaging Plus.

Inbound Webhook setup

WARNING

Currently, Webhook & Webhook secret setup is handled manually.

In future, we plan to implement additional API endpoints for handling this.

Receiving Webhooks

We will make a POST request to the endpoint you specify, containing the information of the inbound message.

In this example, the following parameters are assumed:

• Sender ID from original message: 449999999999
• Webhook endpoint: https://my-website.com/inbound-message
• Signing secret: aaaaaaaaaaaaaaaaaaaaaaaa

Endpoint

A POST request will be made to your endpoint

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

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

Warning!

Messaging Plus expects a 200 response from your endpoint. If it fails to receive a 200 response, it will make 5 additional request attempts.

Verify 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);