Setting up webhooks

Updated 8 March 2026 · 24 views

Webhooks send an HTTP POST request to your server whenever something happens on your account — like a message being delivered or a recipient replying. This lets your application react in real time without polling the API.

The two webhook types

Mobile Message supports two types of webhooks:

Inbound messages — fires when someone replies to your dedicated or shared number, or when someone unsubscribes.

Message status updates (delivery receipts) — fires when a message status changes, such as when it's delivered, sent, or fails.

Configuring webhook URLs

  1. Go to Settings > API
  2. Scroll down to Webhook URLs
  3. Enter your endpoint URL for each webhook type
  4. Click Save Webhook URLs

Webhook URLs section showing input fields for Inbound Messages and Message Status Updates URLs

Leave a field blank to disable that webhook type. Your endpoint must use HTTPS.

Inbound message webhook payload

When someone replies to your number, you'll receive a POST request with this JSON body:

{
  "to": "61400000010",
  "sender": "61412345678",
  "message": "Yes, I'd like to confirm my appointment",
  "received_at": "2026-03-08 14:35:00",
  "type": "inbound",
  "original_message_id": "abcd1234-efgh-5678-ijkl-9876543210mn",
  "original_custom_ref": "tracking001"
}

Field Description

to The dedicated number the reply was sent to

sender The phone number of the person who replied

message The reply text

received_at UTC timestamp when the reply was received

type Either inbound (a reply) or unsubscribe (the recipient opted out)

original_message_id The message_id of the outbound message they're replying to (empty if unknown)

original_custom_ref Your custom_ref from the original message (empty if not provided)

Status update webhook payload

When a message status changes, you'll receive a POST request with this JSON body:

{
  "to": "61412345678",
  "sender": "MyBrand",
  "message": "Your appointment is confirmed for tomorrow at 3pm",
  "custom_ref": "tracking001",
  "status": "delivered",
  "message_id": "abcd1234-efgh-5678-ijkl-9876543210mn",
  "received_at": "2026-03-08 14:35:00",
  "part_number": 1,
  "total_parts": 1
}

Field Description

to The recipient's phone number

sender The sender ID used

message The original message text

custom_ref Your custom reference (if provided)

status The new status: sent, delivered, or failed

message_id The UUID assigned when the message was sent

received_at UTC timestamp of the status update

part_number Which part of the message this status is for

total_parts Total SMS parts for this message

For multi-part messages (messages longer than 160 characters), you'll receive one webhook per part with different part_number values.

Testing webhooks

Before connecting your real server, use a free tool like webhook.site to inspect the raw payloads. Paste the webhook.site URL into your webhook settings, send a test message, and you'll see exactly what data arrives.

Retry behaviour

If your server returns an error or doesn't respond, Mobile Message will retry the webhook with exponential backoff — starting at 60 seconds and increasing up to 1 hour between attempts, for up to 10 retries.

Security tips

  • Always use HTTPS for your webhook URLs
  • Validate the incoming request by checking the payload format matches what you expect
  • Return a 200 status code quickly to acknowledge receipt — do any heavy processing asynchronously

For more on the API, see Getting started with the API and the full API documentation.

Related Articles