Webhooks

Configura un URL di callback HTTPS per ricevere notifiche in tempo reale sullo stato di consegna notifications.

📄️Aggiorna webhook stato di consegna

Sostituisce l'URL di callback del webhook dello stato di consegna esistente con un nuovo URL. Usalo quando l'endpoint del tuo server cambia e vuoi reindirizzare le notifiche senza alcuna interruzione del servizio. L'aggiornamento ha effetto immediato: gli eventi di stato di consegna successivi verranno inviati al nuovo URL. Il nuovo URL di callback viene validato esattamente come in fase di creazione: HTTPS sulla porta 443 o 8443, nessuna credenziale, nessun frammento e un host che si risolve in un indirizzo raggiungibile pubblicamente. Questo endpoint non crea un webhook se non ne esiste uno. Se al momento non è configurato alcun webhook, viene restituito un 404; usa prima POST /webhooks/delivery-status per crearne uno. Restituisce 400 se il corpo della richiesta non è valido: callbackUrl mancante o malformato, uno schema diverso da HTTPS, una porta diversa da 443 o 8443, oppure un host non raggiungibile pubblicamente. Restituisce 401 se la chiave API è mancante o non valida. Restituisce 500 in caso di errore interno.

📄️Revoca webhook stato di consegna

Rimuove definitivamente il webhook dello stato di consegna configurato. Dopo l'eliminazione, non verrà più inviata alcuna notifica di stato di consegna all'URL configurato in precedenza. La modifica ha effetto immediato. Se in futuro dovrai ricevere di nuovo le notifiche, dovrai creare un nuovo webhook con POST /webhooks/delivery-status. Le richieste di notifica in transito già inviate prima dell'eliminazione potrebbero comunque arrivare al vecchio URL; è un comportamento previsto e non indica un errore. Restituisce 204 in caso di successo, senza corpo di risposta. Restituisce 404 se al momento non è configurato alcun webhook. Restituisce 401 se la chiave API è mancante o non valida. Restituisce 500 in caso di errore interno.

📄️Ottieni webhook stato di consegna

Restituisce l'URL di callback HTTPS attualmente configurato per ricevere le notifiche in tempo reale sullo stato di consegna per il tuo account. La piattaforma invia un HTTP POST a questo URL ogni volta che si verifica un evento di stato di consegna per qualsiasi messaggio inviato tramite il tuo account, su tutti i canali (SMS, RCS, WhatsApp). Lo stesso URL di callback è condiviso tra tutti i canali; non configuri URL separati per ciascun canale. Usa questo endpoint per verificare la tua configurazione webhook attuale prima di aggiornare o di risolvere problemi con le callback di stato di consegna. Restituisce 404 se non è stato ancora configurato alcun webhook. Per configurarne uno, usa POST /webhooks/delivery-status. Restituisce 401 se la chiave API è mancante o non valida. Restituisce 500 in caso di errore interno.

📄️Configura webhook stato di consegna

Registra un URL di callback HTTPS per ricevere notifiche in tempo reale sullo stato di consegna. Una volta configurato, la piattaforma invierà una richiesta HTTP POST al tuo URL di callback ogni volta che si verifica un evento di stato di consegna per i messaggi inviati tramite il tuo account. Gli eventi riportano stati come consegnato, scaduto, non recapitabile e altri esiti specifici del canale su SMS, RCS e WhatsApp. L'URL di callback deve usare HTTPS sulla porta 443 o 8443, non deve contenere credenziali né frammenti e deve risolversi in un indirizzo raggiungibile pubblicamente: gli URL che puntano a indirizzi loopback, privati, link-local o comunque interni vengono rifiutati con 400, così come gli host che non si risolvono. Lo stesso URL riceve gli eventi di tutti i canali, come oggetti JSON il cui eventType ne indica il tipo. DELIVERY (SMS, RCS e WhatsApp) viene inviato all'arrivo della ricevuta di consegna e contiene eventType, channel (SMS, RCS o WHATSAPP), messageId (il customerMessageId che hai ricevuto al momento dell'invio), destination, eventDate, price e l'esito della consegna come statusCode numerico con la relativa description; un evento SMS contiene anche totalParts e numPart, con un evento per ogni parte del messaggio. Un messaggio ancora in transito (accepted su SMS, unknown su RCS e WhatsApp) non ha ancora una ricevuta e non genera alcun evento. READ (RCS e WhatsApp) viene inviato quando il destinatario apre il messaggio e contiene eventType, channel, messageId, destination ed eventDate. INBOUND (RCS e WhatsApp) viene inviato quando il destinatario ti scrive e contiene eventType, channel, messageId (l'id del messaggio nella conversazione), source (il numero del destinatario), destination (il tuo numero WhatsApp o l'id dell'agente RCS), receivedDate, messageType, text e, per i contenuti multimediali, mediaKey. I campi senza valore vengono omessi. I valori di statusCode di un evento DELIVERY sono: 1 accepted (SMS, affidato al carrier senza ancora una ricevuta di ritorno), 2 rejected (SMS), 3 delivered, 4 expired, 5 deleted (SMS), 6 undeliverable (SMS), 9 general error (RCS e WhatsApp), 10 disabled (RCS e WhatsApp), 11 unsupported (RCS e WhatsApp), 12 conversation closed (WhatsApp), 0 unknown. Sono gli stessi codici che la tabella Stati di Consegna nella panoramica dell'API associa ai valori deliveryStatus restituiti da GET /partner-gateway/v1/messages/status e GET /partner-gateway/v1/messages/history, e lo stesso numero che la callback di consegna della piattaforma SMS invia come DELIVERY_STATUS. Il tuo server deve rispondere con un codice di stato 2xx entro 5 secondi per confermare la ricezione. Se il tuo endpoint non è raggiungibile o restituisce un errore, la piattaforma ritenta la notifica fino a un totale di 5 tentativi, a distanza di almeno 5 minuti per gli SMS e di almeno 10 minuti per RCS e WhatsApp, per i messaggi inviati negli ultimi 10 giorni. Uno stesso evento può arrivare più di una volta, quindi elabora gli eventi in modo idempotente. Per ogni account può essere attivo un solo URL webhook. Se un webhook è già configurato, questo endpoint restituisce 409 Conflict. In tal caso, usa PUT /webhooks/delivery-status per aggiornare l'URL esistente, oppure DELETE /webhooks/delivery-status per rimuoverlo prima. Restituisce 400 se il corpo della richiesta non è valido: callbackUrl mancante o malformato, uno schema diverso da HTTPS, una porta diversa da 443 o 8443, oppure un host non raggiungibile pubblicamente. Restituisce 401 se la chiave API è mancante o non valida. Restituisce 500 in caso di errore interno.