Setting up webhooks

Updated 14 July 2026 · 573 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.

What to expect for large campaigns

Status webhooks are sent as individual POST requests, one per SMS part. A campaign of 40,000 single-part messages will generate up to 40,000 status events, and more if your message is longer than 160 characters (one event per part, per status change).

A few things to plan for:

  • Events arrive in bursts. Webhooks are queued and delivered in parallel, so expect a high rate shortly after a large send. Return a 200 quickly and do any heavy processing asynchronously.
  • The tail can take a while. Delivery statuses depend on receipts from the mobile networks. Most arrive within minutes, but it's normal for a portion to keep arriving over the following hours, and some stragglers can arrive days after the send. This is normal carrier behaviour, not a fault.
  • received_at is the event time. It records the UTC time of the status update itself, not the time the webhook reached your endpoint, so late or retried webhooks still carry the original event time.
  • Check the delivery log. Settings > API > View Webhook Delivery Logs shows each webhook attempt, its response code, and retry state. It's the quickest way to confirm whether events were sent and received.

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