Respuesta breve
Para recibir los informes de entrega (DLR) con un webhook, exponga un endpoint HTTPS que acepte peticiones POST y registre su URL en su proveedor de mensajería. Guarde cada evento, responda rápido con un código 2xx y procéselo de forma asíncrona. Asocie los eventos a sus registros por ID de mensaje, elimine duplicados y no permita que un estado tardío sobrescriba uno final.
Configurar el endpoint
Durante el desarrollo, un túnel da a un servidor local una URL HTTPS pública.
- Exponga un endpoint HTTPS que acepte peticiones POST con cuerpo JSON.
- Facilite la URL a su proveedor para que la configure en la cuenta o subcuenta correcta.
- Envíe un mensaje de prueba a su propio número y registre el cuerpo bruto del evento.
- Mapee los campos que necesita a partir de eventos reales, no de nombres de campo supuestos.
- Conserve payloads de ejemplo como datos de prueba para cada canal que use.
¿Qué estados recibirá?
Los proveedores traducen los informes de entrega de operadores y canales a sus propios nombres de estado. Este conjunto normalizado es el que usa OmniChannels.ai para SMS, WhatsApp y otros canales.
| Estado | Significado | ¿Final? |
|---|---|---|
| SUBMITTED | Aceptado y en cola | No |
| SENT | Entregado al operador o al canal | No |
| DELIVERED | Confirmado en el dispositivo | Normalmente; puede seguir READ |
| READ | Abierto, en canales que informan de la lectura | Sí |
| FAILED | No entregado, con motivo cuando está disponible | Sí |
| REJECTED | Rechazado, por ejemplo por un ID de remitente (sender ID) sin registrar | Sí |
Haga el handler fiable
- Guarde el cuerpo bruto y después devuelva 2xx. Si falla el guardado, devuelva 5xx para que el evento se reintente.
- Haga el trabajo real en una cola o un worker, no antes de responder.
- Elimine duplicados por ID de mensaje; el mismo estado puede llegar dos veces.
- Jerarquice los estados para que un SENT tardío nunca sobrescriba DELIVERED.
- Acepte los valores de estado que no reconozca en lugar de fallar.
- No reenvíe nunca un mensaje desde el handler del webhook.
Protéjalo y recupere los informes perdidos
Acepte solo HTTPS, use una ruta larga e imposible de adivinar, valide la estructura del cuerpo y confirme el estado con una consulta antes de acciones irreversibles como un reembolso. Si su endpoint estuvo caído, pida al proveedor que reenvíe los informes de entrega de ese periodo o consulte los estados en sus endpoints de informes.
Por SMPP, los informes de entrega llegan como deliver_sm en el bind en lugar de por webhook. Algunos operadores los devuelven tarde o nunca, así que trátelos como un indicio sólido, no como prueba de lectura.