Webhooks
Recibe en tu servidor el estatus de entrega de tus mensajes y las respuestas que envían tus clientes, en tiempo real.
Cómo funciona
Un webhook es una URL de tu servidor a la que SMS Masivos envía eventos cuando ocurren: la confirmación de entrega de un mensaje que enviaste, o una respuesta que tu cliente contesta a uno de tus SMS.
Ambos tipos de evento llegan a la misma URL. Distingue cuál procesar con el parámetro type: confirmation (estatus de entrega) o response (respuesta del cliente). Tu endpoint debe validar type antes de actuar.
Tu endpoint debe cumplir con:
- Aceptar peticiones HEAD (así verificamos que la URL funciona antes de enviarte eventos).
- Recibir los eventos por GET o POST. Si usas POST, acepta el encabezado
Content-Type: application/x-www-form-urlencoded. - Responder HTTP 200 una vez que hayas procesado los parámetros.
Registrar tu webhook
Registra la URL desde el panel en la sección Integraciones (o en Confirmación de entrega), o vía API con POST /webhook/add:
curl -X POST https://api.smsmasivos.com.mx/webhook/add \
-H "Content-Type: application/json" \
-H "apikey: $SMSMASIVOS_API_KEY" \
-d '{
"url": "https://miapp.com/webhooks/sms-masivos",
"status": "1"
}'Gestiona tu webhook con /webhook/get (consultar), /webhook/status (habilitar o deshabilitar) y /webhook/delete (eliminar).
Confirmación de entrega
Cuando type es confirmation, el evento trae el estatus de entrega del mensaje que enviaste. Parámetros:
| Parámetro | Tipo | Descripción |
|---|---|---|
type | Text | confirmation para este evento. |
reference | Text | Identificador del mensaje (el mismo reference que devolvió el envío). |
status | Number | Código de estatus de entrega (ver tabla abajo). |
number | Number | Número del destinatario al que se envió el mensaje. |
date | Text | Fecha y hora de la confirmación, formato AAAAMMDDHHMMSS. |
extra_params | Text | Cadena JSON con los valores que enviaste en extra_params al mandar el mensaje. Ejemplo: {"key_1": "value_1", "key_2": "value_2"}. |
Códigos de status
| Código | Significado |
|---|---|
0 | Entregado |
1 | No entregado |
2 | Desconexión temporal |
3 | Expirado |
4 | Rechazado |
5 | Desconocido |
6 | Número desconocido |
7 | Formato incorrecto |
8 | Error |
9 | Phishing |
10 | Blacklist |
11 | Número fijo |
12 | País no contratado |
Guarda el reference que devuelve cada envío (/sms/send) y crúzalo con el reference del webhook para actualizar el estatus de cada mensaje en tu sistema.
Respuestas de clientes
Cuando type es response, tu cliente respondió a uno de tus SMS y te reenviamos esa respuesta. Parámetros:
| Parámetro | Tipo | Descripción |
|---|---|---|
type | Text | response para este evento. |
reference | Text | Identificador del mensaje original. |
number | Number | Número del destinatario que respondió. |
message | Text | Mensaje que le enviaste al destinatario. |
response | Text | Contenido de la respuesta del destinatario. |
send_date | Text | Fecha y hora de envío del mensaje original, formato AAAAMMDDHHMMSS. |
response_date | Text | Fecha y hora en que se recibió la respuesta, formato AAAAMMDDHHMMSS. |
Reintentos y verificación
- Verificación: antes de enviarte eventos, hacemos una petición HEAD a tu URL para confirmar que responde correctamente.
- Reintentos: si tu endpoint no responde HTTP 200, reintentamos la entrega del evento. Se realizan hasta 25 reintentos por evento.
Responde 200 solo después de haber procesado y guardado los parámetros. Si respondes 200 antes de procesar y tu lógica falla, perderás el evento: para nosotros ya fue entregado.
Con webhooks cierras el ciclo: envías con /sms/send, confirmas la entrega con type: confirmation y atiendes las respuestas con type: response.