Webhook del estado de entrega de SMS que no se activa: guía de debug

Su punto final permanece en silencio, sus tablas no se actualizan.

Este es un problema de configuración clásico en las arquitecturas de eventos. Aquí está cómo deshacer un webhook DLR (Delivery Report) que no se activa.

Cuando envías un SMS a través de una API, la operación es asíncrona. La API toma el mensaje, te da un message_id y luego lo transmite a los operadores (Maroc Telecom, inwi, Orange). Sólo cuando el teléfono de destino confirma la recepción, el operador notifica a la pasarela, que a su vez envía una solicitud HTTP POST a la URL que le proporcionaste (tu Webhook).

Si no recibe nada, la ruptura de comunicación puede situarse en tres niveles.

1. Su URL no es accesible públicamente Si está desarrollando localmente (http://localhost:8000/api/sms/webhook), el servidor de la pasarela SMS no puede acceder a ella. Debe utilizar una herramienta como Ngrok para exponer temporalmente su puerto local a Internet.

2. El Firewall bloquea las IP del proveedor Si su aplicación está en producción, asegúrese de que el firewall de su servidor (o Cloudflare) no bloquee las solicitudes entrantes (POST) de las direcciones IP del proveedor de SMS. Compruebe sus registros WAF (Web Application Firewall) para detectar posibles rechazos '403 Forbidden'.

3. Protección CSRF activada en el punto final Este es el error número 1 con Laravel. Por defecto, Laravel protege todas las consultas POST con un token CSRF (Cross-Site Request Forgery). Dado que el webhook del proveedor SMS no tiene este token, Laravel rechaza la consulta con un error 419 Page Expired. Solución: Agregue la URL de su webhook en las excepciones del middleware VerifyCsrfToken (o coloque el punto final en routes/api.php en lugar de `routes/web.php').

4. Timeout trop court ou script bloquant

Si votre webhook prend trop de temps à répondre parce qu'il effectue des requêtes complexes en base de données ou appelle d'autres services externes, le fournisseur SMS peut considérer que l'appel a échoué (Timeout) après 3 ou 5 secondes.
Votre webhook doit toujours retourner un code HTTP 200 le plus vite possible, avant même de traiter l'information. L'idéal est de placer le payload reçu dans une file d'attente (Queue) et de répondre immédiatement.

La URL está mal configurada en la consulta Asegúrese de que la URL de la webhook esté bien informada, ya sea a nivel global en el dashboard de su proveedor o dinámicamente en la carga de la POST de la solicitud de envío de SMS (a menudo a través de un parámetro callback_url o notify_url).

Para aislar el problema, el método más rápido es usar webhook.site. 1. Generar una URL temporal en webhook.site. 2. Configurar esta URL como webhook de recepción en su proveedor de SMS. 3. Enviar un SMS de prueba. 4. Si recibe la carga de pago en webhook.site, el proveedor está haciendo su trabajo bien: el problema proviene de su código, su firewall o su enrutamiento. 5. Si nada sucede en webhook.site, el problema proviene de la configuración del lado del proveedor (URL no informado, webhooks desactivados en la cuenta, o SMS nunca entregados al operador).

Incluso con una configuración perfecta, un webhook puede fallar (cortar la red, reiniciar su servidor). Compruebe la Retry Policy de su proveedor: ¿cuántas veces se devolverá el webhook en caso de error 500?

Para aplicaciones críticas (banco, OTP transaccional), no confíe únicamente en los webhooks. Implemente un mecanismo de fallback en polling (interrogación regular): si después de 5 minutos todavía no ha recibido un estado para un message_id en Pending, activa un Cron Job (tarea programada) que interrogará manualmente la API (ej.: `GET /v1/messages/{message_id}') para recuperar el estado final con certeza.

// Exemple de code fonctionnel et asynchrone (Laravel minimal)
Route::post('/api/webhooks/sms', function (Request $request) {
    // 1. On stocke le statut dans une file d'attente pour traitement asynchrone
    ProcessSmsDeliveryReport::dispatch($request->all());

    // 2. On répond TOUT DE SUITE avec un code 200 pour éviter le timeout
    return response()->json(['status' => 'received'], 200);
});