Webhooks

How it works

1. 01
   You request your endpoint registration

   You send your URL and short code to support, and the Hablame team registers the endpoint. You get the signing secret in Cloud, only once. Set up webhooks.

2. 02
   An event happens

   When someone texts your short code, Hablame sends your endpoint a POST with the event as JSON. Inbound SMS.

3. 03
   You verify and drop duplicates

   You check the signature with your secret and never process the same X-Hablame-Delivery-Id twice. Verify signatures.

4. 04
   You respond 2xx in time

   You have 15 s. If no 2xx arrives, Hablame retries for 72 hours. Delivery and retries.

Available events

What a notification looks like

Each notification is a POST with a three-key JSON body, id, type and data, plus headers carrying the signature and the delivery identifier.

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"}}

What you need to know

• A notification can arrive more than once. If your response does not arrive in time, it is retried with the same X-Hablame-Delivery-Id: use it to drop duplicates.
• Only a 2xx counts as delivered. A redirect, a 4xx, a 5xx or no response at all is retried.
• There is no attempt limit. A notification stops being retried once it is 72 hours old without being delivered.
• The endpoint is never disabled automatically. If it goes down, it gets fewer attempts in the meantime, and as soon as it responds 2xx it catches up.
• Order is not guaranteed. Up to 8 notifications are delivered at once.
• There is no manual resend. A notification your system lost after responding 2xx will not arrive again.

Next steps