Definizione
Un webhook è una richiesta HTTP che una piattaforma invia a un URL da voi indicato ogni volta che accade un evento, come un messaggio consegnato, letto o non riuscito, o l’arrivo della risposta di un cliente, così il vostro sistema lo apprende subito senza dover interrogare la piattaforma.
Registrate un endpoint (ad esempio https://example.com/hooks/messaging). Quando si verifica un evento, la piattaforma invia una richiesta POST con un corpo JSON che lo descrive: ID del messaggio, stato, data e ora, canale e dettagli dell’errore. Il vostro server dovrebbe rispondere subito con un codice 2xx ed elaborare l’evento in modo asincrono.
Progettate per la consegna nel mondo reale: i webhook possono arrivare in ritardo, fuori ordine o più di una volta. Usate l’ID del messaggio e lo stato per deduplicare, non fate mai tornare indietro uno stato (ad esempio da READ a DELIVERED) e mantenete un gestore idempotente che sia sicuro in caso di nuovi tentativi.
Sicurezza: accettate solo HTTPS, verificate una firma o un segreto condiviso a ogni richiesta e non fidatevi del payload finché non è verificato. Convenzioni di settore come la specifica Standard Webhooks descrivono schemi comuni di firma e nuovi tentativi.
Nella messaggistica, i webhook alimentano rapporti di consegna, tassi di lettura, risposte in arrivo, disiscrizioni e decisioni di fallback tra canali.
OmniChannels.ai invia webhook per gli stati di consegna (SUBMITTED, SENT, DELIVERED, READ, FAILED, REJECTED), normalizzati in un unico formato su tutti i canali.
Esempio
{"messageId":"msg_123","channel":"whatsapp","status":"DELIVERED","timestamp":"2026-10-10T09:15:02Z"}