Webhooks

Cómo funciona

1. 01
   Pides el registro de tu destino

   Le envías a soporte tu URL y tu código corto, y el equipo de Hablame registra el destino. El secreto de firma lo obtienes en Cloud, una sola vez. Activar los webhooks.

2. 02
   Llega un evento

   Cuando una persona le escribe a tu código corto, Hablame le envía a tu destino un POST con el evento en JSON. SMS entrante.

3. 03
   Verificas y descartas repetidos

   Compruebas la firma con tu secreto y no procesas dos veces el mismo X-Hablame-Delivery-Id. Verificar la firma.

4. 04
   Respondes 2xx a tiempo

   Tienes 15 s. Si no llega un 2xx, Hablame lo reintenta durante 72 horas. Entrega y reintentos.

Eventos disponibles

Así llega un aviso

Cada aviso es un POST con un cuerpo JSON de tres llaves, id, type y data, y unas cabeceras con la firma y el identificador de la entrega.

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

Lo que debes saber

• Un aviso puede llegar más de una vez. Si tu respuesta no llega a tiempo, se reintenta con el mismo X-Hablame-Delivery-Id: úsalo para descartar repetidos.
• Solo un 2xx cuenta como entregado. Una redirección, un 4xx, un 5xx o la falta de respuesta se reintentan.
• No hay tope de intentos. Un aviso deja de intentarse cuando cumple 72 horas sin entregarse.
• El destino nunca se deshabilita solo. Si se cae, recibe menos intentos mientras tanto, y en cuanto responde 2xx se pone al día.
• El orden no está garantizado. Se entregan hasta 8 avisos a la vez.
• No hay reenvío manual. Un aviso que tu sistema perdió después de responder 2xx no vuelve a llegar.

Siguientes pasos