Uso correcto de los webhooks de Delivery Report (DLR): arquitectura y mejores prácticas

Para saber qué está sucediendo "en el terreno" (¿IAM bloqueó el SMS? ¿El número está fuera de servicio? ¿Está el teléfono apagado?), es necesario escuchar la red. Esta es la función fundamental del Informe de entrega (DLR).

En lugar de sondear la plataforma en un bucle para preguntar por el estado (Polling), una práctica engorrosa e ineficiente, el método moderno consiste en utilizar un Webhook. Nuestro servidor "envía" el resultado al suyo tan pronto como el operador marroquí nos responde. Aquí se explica cómo diseñar esto.

Cuando el operador (IAM, Orange, inwi) actualiza el estado del mensaje, nuestra API activa una solicitud HTTP POST a la URL que hayas configurado en tu área de cliente.

La carga útil (cuerpo de la solicitud) está en este estricto formato JSON:

{
  "message_id": "msg_5f8b3c9a2d1e4",
  "phone_number": "+212600000000",
  "status": "DELIVERED",
  "operator": "INWI",
  "error_code": null,
  "timestamp": "2026-06-25T14:32:01Z",
  "price_mad": 0.65,
  "segments": 1
}

Los estados posibles son generalmente: PENDIENTE (En cola), ENTRADO (Entregado al terminal), RECHAZADO (Rechazado por el operador, a menudo un problema de ID del remitente en la lista negra) o FAILED (Error en la entrega, como un número no válido).

El mayor error técnico es vincular la recepción del webhook directamente a una interfaz de usuario o a una computación intensa. El endpoint del webhook debe responder a nuestra plataforma con un HTTP 200 rápidamente (dentro del tiempo límite asignado), de lo contrario nuestro sistema considerará que estás caído e intentará reiniciar el webhook (Reintentar).

Arquitectura recomendada:

1. El webhook recibe el JSON.
2. Valida la firma de seguridad (HMAC).
3. Inserta los datos sin procesar de forma asíncrona en una tabla SQL optimizada para lectura (o los envía a una cola RabbitMQ/Kafka).
4. Responde "HTTP 200 OK" inmediatamente.

Esquema de tabla mínimo (MySQL / PostgreSQL):```sql
CREATE TABLE sms_delivery_logs (
id BIGINT AUTO_INCREMENT PRIMARY KEY,
message_id VARCHAR(64) UNIQUE NOT NULL,
campaign_id INT NULL,
phone_number VARCHAR(20) NOT NULL,
status VARCHAR(20) NOT NULL, -- DELIVERED, FAILED, etc.
error_code VARCHAR(10) NULL,
operator VARCHAR(20) NULL,
delivered_at DATETIME NULL,
INDEX idx_status (status),
INDEX idx_campaign (campaign_id)
);

Una vez que estos datos se almacenan en tiempo real, ya no es necesario esperar a que finalice la campaña para reaccionar. Puede crear un panel interno (Grafana, Metabase o un panel de administración personalizado) que monitoree estas 3 métricas vitales:

1. El Ratio de Entrega: (Nb Entregados / Total Enviados) * 100. Si cae por debajo del 90%, se requiere acción inmediata.
2. Tiempo de entrega (Latencia): La diferencia horaria entre la fecha de envío y la "marca de tiempo" del estado "ENTRADO". Si supera los 30 segundos para una OTP, seguramente el cliente ya ha abandonado su transacción.
3. Desglose por operador: Si el 99% de los envíos de Orange son "ENTREGADOS" pero el 80% de los envíos de IAM son "RECHAZADOS", habrá diagnosticado un problema de lista blanca de un vistazo.

En lugar de mirar el tablero todo el día, deje que los datos le avisen. Configure un script que se ejecute cada 15 minutos durante sus envíos masivos.

Si detecta un pico inusual en los estados "FALLADO" o "RECHAZADO" (por ejemplo: +20% de fallas en los últimos 5 minutos), el script activa una alerta de Slack/Teams o envía un correo electrónico de emergencia a DevOps y al gerente de Marketing. Esto le permite detener inmediatamente una campaña defectuosa antes de gastar todo su presupuesto de SMS en el vacío.