Inbound SMS

Someone sent an SMS to your short code. It reaches you as the sms.mo.{shortCode} event.

3 min read

When it arrives

Every time an SMS reaches a short code that has a registered endpoint. The type ends with the short code, lowercased and trimmed: an SMS to 87654 arrives as sms.mo.87654.

Who receives it

You register an endpoint per short code, naming it: sms.mo.87654. An endpoint that does not name the short code does not receive its SMS. If a short code has no registered endpoint, the SMS it receives are discarded: they are not stored or delivered later.

To register your short code, follow Set up webhooks.

What it contains

data fields
Field	Type	What it is	Example
`shortCode`	string	The short code the message was sent to.	`87654`
`from`	string	The sender’s mobile number, in international format and without the `+` sign.	`573001234567`
`text`	string	The message text, already decoded (accents included).	`Hola, quiero más información`
`receivedAt`	string	When Hablame processed it to send it to you, in UTC with seconds (RFC 3339).	`2026-10-24T15:04:05Z`
`messageId`	string	Message identifier, shaped like a UUID. Without dashes and lowercased, it is the event `id`.	`0192f0c4-7b1e-7a3d-9c55-3e2a1b4c5d6e`

The same body, indented for reading. What is signed is the exact text that arrives, without indentation.

{
  "id": "0192f0c47b1e7a3d9c553e2a1b4c5d6e",
  "type": "sms.mo.87654",
  "data": {
    "shortCode": "87654",
    "from": "573001234567",
    "text": "Hola, quiero más información",
    "receivedAt": "2026-10-24T15:04:05Z",
    "messageId": "0192f0c4-7b1e-7a3d-9c55-3e2a1b4c5d6e"
  }
}

The full notification

What your endpoint receives (example signed with the example secret)

POST /webhooks/hablame HTTP/1.1
Host: tu-dominio.com
Content-Type: application/json
User-Agent: Hablame-Webhooks/1
X-Hablame-Event-Type: sms.mo.87654
X-Hablame-Delivery-Id: wdl_01K8F3Q2Z9X7V4N6B5C2D1E0FA
X-Hablame-Timestamp: 1792854247
X-Hablame-Signature: sha256=333ed7a2b59cd8511cfefec69da4e04d6ef9925444f1225a97f729512b2ff04b
Idempotency-Key: wdl_01K8F3Q2Z9X7V4N6B5C2D1E0FA

{"id":"0192f0c47b1e7a3d9c553e2a1b4c5d6e","type":"sms.mo.87654","data":{"shortCode":"87654","from":"573001234567","text":"Hola, quiero más información","receivedAt":"2026-10-24T15:04:05Z","messageId":"0192f0c4-7b1e-7a3d-9c55-3e2a1b4c5d6e"}}

Duplicates and several endpoints

The same notification can arrive more than once with the same X-Hablame-Delivery-Id. Drop it if you already have it.
If you registered several endpoints for the same short code, each gets its own X-Hablame-Delivery-Id, but the event id is the same for all of them. If those endpoints write to the same database, use the id to avoid storing the same SMS twice.

Keep in mind

A long SMS arrives as several events, one per fragment, and today it carries no data to join them.
Inbound SMS arrive only by webhook; they are not received over the SMPP connection.
After the endpoint is registered, notifications can take up to 30 seconds to start arriving.