Overview
Se i webhook di BroadNet relativi ai report di consegna (DLR) non raggiungono il tuo server, la causa è quasi sempre da ricercare sul lato ricevente: mancata configurazione di un URL di callback sull'account, URL non accessibile pubblicamente tramite HTTPS o endpoint che non restituisce rapidamente un codice HTTP 200. La piattaforma invia tramite POST un DLR in formato JSON (MessageId, Status, BatchId e altro) al tuo URL ogni volta che un messaggio raggiunge uno stato finale: verifica prima l'URL, la risposta e il tuo firewall.
URL di callback non configurato (o errato)
I webhook DLR si attivano solo se è impostato un URL di callback sul tuo account. Se non ne è configurato alcuno, o se punta a un host vecchio o errato, non verrà inviato nulla e non verrà visualizzato alcun errore. Verifica l'URL DLR/webhook sul tuo account e, se non riesci a ricevere alcuna notifica push, recupera lo stato su richiesta (tramite l'API HTTP legacy: GET /websmpp/websmsstatus con l'ID di risposta).
- I webhook richiedono che un URL di callback sia impostato sull'account.
- Un URL mancante o obsoleto comporta la mancata consegna silenziosa.
- Verificare che l'URL DLR configurato sia aggiornato.
- Alternativa: recupera lo stato su richiesta (API HTTP legacy: /websmpp/websmsstatus).
Endpoint non raggiungibile pubblicamente tramite HTTPS
La piattaforma effettua richieste POST da Internet pubblico, quindi localhost, un IP privato, un certificato TLS non attendibile/autofirmato o una lista di indirizzi IP consentiti che esclude i nostri mittenti impediranno la corretta ricezione della callback. Esporre un endpoint HTTPS pubblico con un certificato valido e, se si utilizza una lista di indirizzi consentiti, autorizzare gli indirizzi in uscita di BroadNet. Testare l'URL dall'esterno della propria rete prima di attribuire la colpa alla piattaforma.
- Deve trattarsi di un URL HTTPS pubblico con un certificato valido.
- localhost, indirizzi IP privati e certificati autofirmati non saranno ricevuti.
- Se si filtra il traffico in entrata, è possibile inserire i mittenti di BroadNet nella lista dei mittenti consentiti.
- Esegui un comando curl sull'endpoint dall'esterno della tua rete per verificarne la raggiungibilità.
L'endpoint non restituisce rapidamente il codice 200.
Il tuo endpoint deve rispondere immediatamente con HTTP 200. Se restituisce un codice 4xx/5xx, va in timeout o si blocca durante un'operazione complessa, la consegna viene considerata fallita e ritentata con un backoff esponenziale, il che si traduce in webhook "mancanti" o ritardati. Restituisci immediatamente 200 ed elabora il DLR in modo asincrono (mettilo in coda, poi esegui l'operazione).
- Conferma con HTTP 200 fast.
- 5xx/4xx/timeout → tentativi con backoff (sembra che vengano persi).
- Non rallentare il lavoro prima di aver risposto.
- Restituisci 200, quindi elabora il DLR dal percorso della richiesta.
Non si tratta di un problema di webhook: il messaggio non è ancora definitivo.
Un DLR si attiva solo quando un messaggio raggiunge uno stato terminale (DELIVRD o UNDELIV). Se un messaggio è ancora in coda o programmato, non è ancora previsto alcun report: questo è normale e non indica un errore del webhook. Prima di concludere che il webhook non funziona, conferma lo stato effettivo del messaggio con un recupero dello stato (API HTTP legacy: /websmpp/websmsstatus) e associa i report tramite MessageId o BatchId.
- I DLR si attivano solo nello stato finale (DELIVRD / UNDELIV).
- I messaggi in coda o programmati non dispongono ancora di DLR.
- Prima di procedere con il debug, verificare lo stato reale recuperandolo (API HTTP legacy: /websmpp/websmsstatus).
- Corrispondenza dei report in base a MessageId o BatchId.