Risposta breve
Per ricevere i rapporti di consegna con un webhook, esponete un endpoint HTTPS che accetti richieste POST e registrate il suo URL presso il vostro provider di messaggistica. Salvate ogni evento, rispondete subito con uno stato 2xx ed elaborate in modo asincrono. Associate gli eventi ai vostri record tramite l’ID messaggio, deduplicateli e non lasciate mai che uno stato tardivo sovrascriva uno finale.
Configurare l’endpoint
In fase di sviluppo, un tunnel dà a un server locale un URL HTTPS pubblico.
- Esponete un endpoint HTTPS che accetti richieste POST con corpo JSON.
- Comunicate l’URL al provider, in modo che venga configurato sull’account o sul sotto-account corretto.
- Inviate un messaggio di prova al vostro numero e registrate il corpo grezzo dell’evento.
- Mappate i campi che vi servono partendo dagli eventi reali, non da nomi di campo presunti.
- Conservate payload di esempio come fixture di test per ogni canale che usate.
Quali stati riceverete?
I provider traducono i rapporti di operatori e canali nei propri nomi di stato. Questo insieme normalizzato è quello che OmniChannels.ai usa su SMS, WhatsApp e altri canali.
| Stato | Significato | Finale? |
|---|---|---|
| SUBMITTED | Accettato e messo in coda | No |
| SENT | Consegnato all’operatore o al canale | No |
| DELIVERED | Confermato sul dispositivo | Di solito; può seguire READ |
| READ | Aperto, sui canali che riportano le letture | Sì |
| FAILED | Non consegnato, con il motivo dove disponibile | Sì |
| REJECTED | Rifiutato, ad esempio per un Sender ID non registrato | Sì |
Rendere affidabile il gestore
- Salvate il corpo grezzo, poi restituite 2xx. Se il salvataggio fallisce, restituite 5xx così l’evento può essere ritentato.
- Svolgete il lavoro vero in una coda o in un worker, non prima di rispondere.
- Deduplicate per ID messaggio: lo stesso stato può arrivare due volte.
- Assegnate un ordine di priorità agli stati, così un SENT tardivo non sovrascrive mai un DELIVERED.
- Accettate i valori di stato che non riconoscete invece di andare in errore.
- Non rinviate mai un messaggio dall’interno del gestore del webhook.
Proteggerlo e recuperare i rapporti persi
Accettate solo HTTPS, usate un percorso lungo e non indovinabile, convalidate la struttura del corpo e confermate lo stato con una chiamata di stato prima di azioni irreversibili come i rimborsi. Se il vostro endpoint era fuori servizio, chiedete al provider di reinviare i rapporti del periodo oppure leggete gli stati dai suoi endpoint di reportistica.
Con SMPP i rapporti arrivano come deliver_sm sul bind anziché tramite webhook. Alcuni operatori restituiscono i rapporti in ritardo o per niente, quindi considerateli una prova solida, non la certezza dell’avvenuta lettura.