Un webhook SMS es una URL en tu servidor que recibe notificaciones automáticas cuando un mensaje se entrega, falla o cuando alguien responde. Con SMS Masivos lo configuras en menos de 5 minutos desde el panel: ingresas tu URL, eliges los eventos, y empiezas a recibir POSTs con JSON. Sin polling, sin SDK propietario.
Si alguna vez has enviado miles de SMS y te has preguntado cuáles llegaron realmente, ya conoces el problema. Revisar reportes a mano o hacer polling cada 30 segundos no escala. Los webhooks resuelven exactamente eso: tu sistema recibe el evento en el momento que ocurre, no cuando decides ir a buscarlo.
Esta guía cubre cómo funciona el flujo completo, cómo implementar el handler en Node.js y Python, y qué hacer con los eventos para construir integraciones sólidas.
Qué es un webhook SMS y cuándo usarlo
Un webhook es un endpoint HTTP en tu servidor que recibe eventos en tiempo real enviados por un proveedor externo, en este caso SMS Masivos, cada vez que algo relevante ocurre con tus mensajes.
Hay dos tipos de eventos que recibirás:
- DLR (Delivery Report): confirmación de que el mensaje llegó al dispositivo del destinatario, con el status final: DELIVERED, FAILED, EXPIRED o PENDING.
- MO (Mobile Originated): cuando el destinatario responde tu SMS, el texto entrante llega a tu webhook con el número del remitente y el contenido.
¿Por qué importa la diferencia con polling? Con polling, haces una solicitud GET a la API cada N segundos para preguntar si hubo cambios. Con webhooks, recibes el evento en cuanto ocurre. Para un OTP con ventana de 60 segundos, la diferencia entre polling cada 10 segundos y un webhook instantáneo puede ser la diferencia entre que el usuario complete el login o lo abandone.
Casos de uso comunes en México:
- Fintechs que bloquean operaciones si el OTP no fue entregado confirmado por DLR
- E-commerce que actualiza el estado de un pedido en su CRM cuando el SMS de envío llega al cliente
- Clínicas que capturan respuestas "C" (confirmar) o "X" (cancelar) de recordatorios de cita
- Cobranza que registra automáticamente cuando un cliente responde "PAGADO"
Cómo funciona el flujo de eventos
El flujo completo de un DLR tiene cinco pasos:
- Tu app llama a
POST /sms/senden la API de SMS Masivos con los parámetros del mensaje. - SMS Masivos enruta el mensaje al carrier correspondiente (Telcel, AT&T, Movistar, Altán).
- El carrier confirma la entrega al dispositivo del destinatario.
- SMS Masivos recibe esa confirmación y construye el payload JSON del evento.
- SMS Masivos hace un POST a tu webhook URL con el payload.
El tiempo total entre los pasos 1 y 5 suele ser menor a 3 segundos para DELIVERED en redes directas. Para FAILED o EXPIRED, el evento llega cuando expira el TTL del carrier (normalmente entre 24 y 48 horas si el teléfono estuvo apagado).
Una estructura típica del payload JSON es la siguiente (los nombres de campo exactos pueden variar; consulta la documentación de tu cuenta para el schema completo):
{
"id": "evt_7f3a9c12d4e",
"type": "DLR",
"status": "DELIVERED",
"to": "+5215512345678",
"from": "SMSMASIVOS",
"message_id": "msg_3e8b1d",
"timestamp": "2026-04-27T15:42:18Z",
"metadata": {
"campaign_id": "camp_9f2c",
"country_code": "52"
}
}Los valores posibles del campo status:
| Status | Significado | Cuándo ocurre |
|---|---|---|
| DELIVERED | Entregado al dispositivo | Mensaje recibido en el celular |
| FAILED | Fallo definitivo | Número inexistente, rechazado por carrier |
| PENDING | En tránsito | Enviado al carrier, esperando confirmación |
| EXPIRED | Venció el TTL | El dispositivo no estuvo disponible en 24-48h |
Configurar tu webhook en SMS Masivos
Antes de escribir una sola línea de código, necesitas tener tu endpoint en una URL pública. Para desarrollo local puedes usar ngrok o localtunnel para exponer un puerto local temporalmente.
Una vez que tienes tu URL:
- Entra a tu cuenta de SMS Masivos.
- Ve a Configuración > API > Webhooks.
- Ingresa la URL de tu endpoint (debe ser HTTPS en producción).
- Genera o copia tu webhook secret. Lo usarás para validar la firma de cada evento.
- Selecciona los eventos que quieres recibir: DLR, MO o ambos.
- Guarda y haz clic en "Enviar evento de prueba".
Si tu endpoint responde 200 OK, la configuración es correcta. Si no, el panel muestra el código de respuesta y los headers que devolviste, lo cual acelera el debug.
SMS Masivos también soporta modo sandbox: si envías mensajes con sandbox=1 en la API, los eventos de delivery se disparan contra tu webhook sin consumir saldo real. Úsalo durante el desarrollo.
Implementar el handler en Node.js
El handler tiene tres responsabilidades: validar la firma, procesar el evento y responder 200 rápido. El ejemplo usa Express.js con el módulo nativo crypto de Node.js.
// webhook-handler.js - Node.js + Express
const express = require('express');
const crypto = require('crypto');
const app = express();
const WEBHOOK_SECRET = process.env.SMSA_WEBHOOK_SECRET;
// Parsear el body como texto plano para validar firma
app.use('/webhook/sms', express.text({ type: '*/*' }));
app.post('/webhook/sms', (req, res) => {
// 1. Validar firma HMAC-SHA256 (header name según docs de tu cuenta)
const signature = req.headers['x-smsa-signature'];
const expected = crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(req.body)
.digest('hex');
if (signature !== expected) {
return res.status(401).json({ error: 'Invalid signature' });
}
// 2. Parsear el payload
const event = JSON.parse(req.body);
// 3. Responder 200 ANTES de procesar (evitar timeouts)
res.status(200).json({ received: true });
// 4. Procesar de forma asíncrona
handleEvent(event);
});
function handleEvent(event) {
if (event.type === 'DLR') {
console.log(`SMS ${event.message_id} → ${event.status} para ${event.to}`);
// Aquí: actualizar DB, activar lógica de negocio
} else if (event.type === 'MO_RECEIVED') {
console.log(`Respuesta de ${event.from}: "${event.message}"`);
// Aquí: procesar respuesta, actualizar CRM
}
}
app.listen(3000, () => console.log('Webhook handler en puerto 3000'));
Tres puntos críticos de este código:
- Parsear como texto antes de validar: si parseas como JSON primero, el body ya no está en su forma original y la firma no coincide.
- Responder antes de procesar: SMS Masivos espera la respuesta en menos de 10 segundos. Si tu lógica de negocio puede tardar más (escritura a DB lenta, llamada a API externa), responde 200 inmediatamente y procesa en background.
- Variable de entorno para el secret: nunca hardcodees el secret en el código fuente.
Implementar el handler en Python
La misma lógica en Flask:
# webhook_handler.py - Python + Flask
import hmac
import hashlib
import json
import os
from flask import Flask, request, jsonify
app = Flask(__name__)
WEBHOOK_SECRET = os.environ['SMSA_WEBHOOK_SECRET'].encode()
@app.route('/webhook/sms', methods=['POST'])
def sms_webhook():
# 1. Validar firma HMAC-SHA256 (header name según docs de tu cuenta)
raw_body = request.get_data()
signature = request.headers.get('X-SMSA-Signature', '')
expected = hmac.new(WEBHOOK_SECRET, raw_body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(signature, expected):
return jsonify({'error': 'Invalid signature'}), 401
# 2. Responder 200 inmediatamente
event = json.loads(raw_body)
process_event(event) # En prod: usa una cola (Celery, RQ) para esto
return jsonify({'received': True}), 200
def process_event(event):
if event.get('type') == 'DLR':
print(f"SMS {event['message_id']} → {event['status']} para {event['to']}")
elif event.get('type') == 'MO_RECEIVED':
print(f"Respuesta de {event['from']}: {event.get('message', '')}")
if __name__ == '__main__':
app.run(port=3000)
Nota: en Python usa hmac.compare_digest en lugar de == para la comparación. Evita ataques de timing donde un atacante puede inferir cuántos caracteres del secret acertó midiendo el tiempo de respuesta.
Casos de uso reales para integraciones en México
Los tres patrones que aparecen más seguido en apps mexicanas:
OTP con delivery gate. Envías el OTP con POST /sms/send. Cuando el DLR llega como DELIVERED, activas un flag en tu sesión de usuario: "OTP llegó, puede proceder al login." Si el DLR llega como FAILED o no llega en 60 segundos, ofreces reenvío. Esto reduce el abandono en flows de verificación donde el usuario no sabe si el SMS está en camino o ya falló.
Confirmación de citas por respuesta. Envías un recordatorio: "Tu cita es mañana a las 10am. Responde C para confirmar o X para cancelar." Cuando el webhook recibe un evento MO con el texto del destinatario, tu app actualiza el status de la cita en tu CRM sin que nadie tenga que revisar el panel manualmente. Estudios de salud digital en México reportan reducciones de no-shows entre 25% y 35% en consultorios que implementan recordatorios automatizados.
Registro de entrega en logística. Para mensajes transaccionales de rastreo de paquetes, el DLR confirma que el destinatario recibió la notificación en su dispositivo. Esto es auditable: si el cliente dice que no le avisaron, tienes el timestamp exacto del DLR como evidencia.
SMS Masivos es una plataforma mexicana de mensajería empresarial con 15 años de operación, conexión directa a los cuatro carriers principales (Telcel, AT&T, Movistar, Altán) y tasa de entrega del 99% en cobertura nacional. Los webhooks están disponibles en todos los planes desde la cuenta básica.
¿Quieres implementar OTP con webhook incluido? Revisa la página de verificación OTP para ver el flujo completo con fallback automático SMS, WhatsApp y voz.
Crea tu cuenta en SMS Masivos y configura tu primer webhook en menos de 10 minutos.
Seguridad y mejores prácticas
Cuatro reglas que evitan el 95% de los problemas:
Valida siempre la firma HMAC. Sin esta validación, cualquier persona que conozca tu URL puede enviar eventos falsos a tu sistema. El secret que genera SMS Masivos es el mecanismo de autenticación. No lo saltes "para simplificar".
Responde en menos de 10 segundos. Si tu handler tarda más, SMS Masivos marca el intento como fallido y reintenta. Si tienes lógica pesada (queries lentas, APIs externas), usa una cola: pone el evento en Redis o una cola en memoria y procesa en un worker separado. El handler solo recibe y encola.
Implementa idempotencia con el campo id. SMS Masivos puede enviarte el mismo evento más de una vez si no recibió tu respuesta 200 a tiempo (red inestable, reinicio de servidor). Guarda los IDs procesados en una tabla o cache y descarta duplicados. Sin esto, podrías procesar el mismo pago dos veces o actualizar el status de una cita varias veces.
HTTPS obligatorio en producción. En desarrollo puedes aceptar HTTP para pruebas locales con ngrok, pero en producción el endpoint debe estar en HTTPS. Los datos de los eventos incluyen números de teléfono y pueden incluir fragmentos del mensaje.
Preguntas frecuentes sobre webhooks SMS
¿Qué pasa si mi endpoint no responde en tiempo?
SMS Masivos reintenta el webhook automáticamente si tu endpoint devuelve un código diferente de 2xx o no responde en el tiempo límite. Si todos los intentos fallan, el evento queda en estado fallido y puedes revisarlo desde el panel de actividad de webhooks. Diseña tu infraestructura para que el handler de webhooks sea el servicio más estable de tu stack.
¿Los webhooks funcionan en el modo sandbox?
Sí. Envía un SMS con sandbox=1 en la API y el evento de delivery se dispara contra tu webhook URL igual que en producción, sin consumir saldo. Es el entorno correcto para hacer pruebas de integración completas.
¿Puedo recibir respuestas de mis contactos (MO)?
Sí, siempre que tu cuenta tenga configurado un número de respuesta. Cuando un contacto responde tu SMS, llega un evento de tipo MO_RECEIVED con el número del remitente, el texto y el timestamp. Úsalo para capturar confirmaciones, respuestas a encuestas o cualquier flujo de dos vías.
Si ya tienes una cuenta en SMS Masivos, la configuración del webhook tarda menos de 10 minutos: crea el endpoint, regístralo en el panel, valida con el evento de prueba y listo. Si todavía no tienes cuenta, puedes crear una y probar el sandbox sin costo adicional desde el primer día.
Para más contexto sobre la API en general, lee la guía de API SMS para México. Si prefieres empezar con los lenguajes de programación, el tutorial completo de Python y Node.js cubre el flujo de envío desde cero. Y si el caso de uso principal es OTP, el artículo sobre qué es un OTP explica los fundamentos antes de entrar a la integración técnica.
Crea tu cuenta en SMS Masivos y configura tu primer webhook hoy.
