Webhook
Aggiornato il
Dove: Impostazioni > Integrazioni > Webhook
A cosa serve:
"Inoltra gli eventi in arrivo al tuo server" SyBox inoltra una copia di ogni evento selezionato a un endpoint sul tuo server in tempo reale. Gli eventi di WhatsApp arrivano nel formato proprio di Meta. I messaggi dei clienti su Messenger, Instagram, Telegram, TikTok e Live Chat, così come gli eventi delle conversazioni (completata, etichette, contatti, trattative, pratiche CRM), arrivano nel formato proprio di SyBox. I messaggi email e SMS non vengono inoltrati.
Chi può aprirla: l'amministratore principale e i membri del team con il permesso "Gestisci i canali". Per creare un webhook o riattivarne uno in pausa, è necessario anche il permesso "Mostra il numero del contatto", poiché le notifiche includono i numeri di telefono reali dei clienti.
Eventi disponibili:
- "Messaggio in arrivo": un cliente ha inviato un messaggio.
- "Stato del messaggio": un messaggio inviato è stato spedito, consegnato, letto o non è stato recapitato.
- "Reazione": un cliente ha reagito a un messaggio.
- "Conversazione contrassegnata come completata": una conversazione è stata contrassegnata come completata da un membro del team, da un'automazione o automaticamente dopo il silenzio del cliente.
- "Etichetta aggiunta o rimossa": un'etichetta è stata aggiunta o rimossa da una conversazione.
- "Contatto creato o aggiornato": è stato creato un nuovo contatto oppure sono cambiati il nome, l'email o i campi di un contatto. Un'importazione di contatti non invia questi eventi.
- "Trattativa chiusa": è stata registrata una trattativa in una conversazione.
- "Pratica CRM aperta o chiusa": una pratica CRM è stata aperta, oppure chiusa come risolta, non risolta o annullata. Una pratica non appartiene ad alcun numero, quindi la riceve solo un webhook che copre tutti i numeri, non uno limitato ad alcuni numeri.
Gli ultimi cinque arrivano nel formato proprio di SyBox, per ogni canale. La pagina Documentazione per gli sviluppatori mostra un esempio di ciascuno.
- "Trascrizione vocale" (opzione aggiuntiva): il messaggio vocale viene trattenuto per un breve intervallo (fino a circa due minuti) per consentire l'invio del testo trascritto insieme ad esso. È disattivata se non viene abilitata esplicitamente.
- Vai su Impostazioni > Integrazioni > Webhook.
- Clicca su "Aggiungi webhook".
- Inserisci un "Nome".
- Inserisci l'"URL di destinazione". Deve essere "Un indirizzo https pubblico raggiungibile". Gli indirizzi http non protetti e gli indirizzi di reti private o interne vengono rifiutati.
- Sotto "Eventi", attiva almeno un evento. "Messaggio in arrivo" è attivo per impostazione predefinita.
- Facoltativo: attiva "Trascrizione vocale" per ricevere i messaggi vocali accompagnati dal loro testo.
- Sotto "Numeri", lascia attivo "Tutti i numeri" per includere qualsiasi numero WhatsApp. In alternativa, disattivalo e seleziona solo i numeri desiderati.
- Clicca su Salva.
- Una finestra mostrerà la "Chiave di firma". "Copiala ora — viene mostrata una sola volta" Salvala sul tuo server.
Dettagli sull'inoltro degli eventi:
- Ogni notifica utilizza lo stesso formato dei webhook WhatsApp ufficiali di Meta.
- Ogni invio viene firmato con la tua chiave di firma, nello stesso modo in cui Meta firma i propri webhook. Se il tuo server valida già i webhook di Meta, potrà verificare quelli di SyBox utilizzando la chiave di SyBox.
- Se il tuo server non risponde con esito positivo, SyBox ritenta più volte con intervalli crescenti per circa un'ora, dopodiché interrompe i tentativi per quell'evento.
- Lo stesso evento potrebbe talvolta essere recapitato due volte, ad esempio a seguito di un timeout. È consigliabile gestire l'idempotenza sul tuo server.
- Assicurati che il webhook sia attivo. Se è disattivato, vedrai "Attiva prima questo webhook."
- Sulla sua scheda, fai clic su "Invia evento di test". Vedrai "Un evento di test è in arrivo. Il risultato apparirà in Consegne."
- Pochi secondi dopo si apre l'elenco "Consegne" che mostra la risposta del tuo server. La scheda mostra anche l'ultima risposta ricevuta dal tuo server con l'orario. Una risposta corretta (ad esempio "HTTP 200") appare in verde. Gli errori appaiono in rosso. "Ultima consegna: mai" indica che non è ancora stato recapitato alcun evento.
Un evento di test contiene "event": "test" e non trasporta dati dei clienti. Puoi inviarne uno ogni pochi secondi; se riprovi prima, vedrai "È stato inviato un test poco fa. Riprova tra qualche secondo."
- Sulla scheda del webhook, fai clic su "Consegne".
- L'elenco mostra "Le ultime 50 consegne degli ultimi 7 giorni.", dalla più recente. Ciascuna indica l'evento, quando è stato effettuato il tentativo e il suo stato:
- "Consegnato": il tuo server ha risposto con successo.
- "In attesa di invio": non è ancora stato effettuato alcun tentativo.
- "Non riuscito, nuovo tentativo in corso": il tuo server non ha risposto con successo e SyBox riproverà più tardi.
- "Non consegnato": SyBox ha smesso di riprovare.
- Mostra anche il codice HTTP con cui ha risposto il tuo server, la durata della risposta in millisecondi e "Tentativi: [numero]" quando è stato provato più di una volta. Il messaggio stesso non viene mostrato.
- Per inviarne nuovamente una, fai clic su "Invia di nuovo" su una consegna con stato "Consegnato" o "Non consegnato". Vedrai "Messo in coda per un nuovo invio." Il nuovo invio richiede il permesso "Mostra il numero del contatto", perché invia nuovamente i dati del cliente.
Disattivato automaticamente:
Se il tuo server continua a restituire errori — 20 tentativi consecutivi per più di un'ora — SyBox disattiva il webhook. La scheda mostra in rosso "Disattivato automaticamente dopo [numero] consegne non riuscite consecutive" e l'amministratore principale riceve la notifica "Un webhook è stato disattivato". Gli eventi in attesa vengono conservati per 24 ore. Correggi l'indirizzo o il server, quindi riattiva il webhook: gli eventi in attesa verranno inviati e il conteggio ripartirà da zero.
- Clicca su Modifica per aggiornare nome, indirizzo, eventi o numeri associati.
- Per rigenerare la chiave di firma, inseriscine una nuova in "Chiave di firma". Lascia vuoto il campo per mantenere quella in uso ("Lascia vuoto per mantenere la chiave attuale").
- Clicca su Abilita / Disabilita per sospenderlo. Gli eventi generati durante la sospensione rimarranno in coda e verranno inviati riattivando il webhook a breve.
- Clicca su Elimina, quindi conferma con "Eliminare questo webhook?".
Regole e messaggi:
- Il Nome e l'URL di destinazione sono obbligatori, e almeno un evento deve essere selezionato. In caso contrario comparirà il messaggio "Dati incompleti".
- Qualsiasi indirizzo non https pubblico verrà rifiutato con "Un indirizzo https pubblico raggiungibile".
Ho perso la chiave di firma.
Non può essere mostrata nuovamente. Modifica il webhook, inserisci una nuova chiave a tua scelta in "Chiave di firma", salva e aggiorna il valore sul tuo server.
Il mio webhook è stato disattivato senza che io facessi nulla.
SyBox lo ha disattivato dopo che il tuo server ha restituito errori per 20 volte consecutive per più di un'ora. Vedi "Disattivato automaticamente" qui sopra: ripara il server e riattiva il webhook entro 24 ore affinché gli eventi in attesa vengano inviati.
Il mio webhook non riceve alcun dato.
Fai prima clic su "Invia evento di test" sulla sua scheda e controlla in "Consegne". Verifica poi questi quattro elementi: (1) il webhook è attivo; (2) è stato selezionato almeno un evento; (3) è associato al numero WhatsApp corretto o a "Tutti i numeri"; (4) il canale da cui è arrivato il messaggio è tra quelli supportati dai webhook (WhatsApp, Messenger, Instagram, Telegram, TikTok o Live Chat; non email o SMS). Controlla poi l'esito dell'ultima consegna sulla scheda.
La scheda mostra un errore in rosso, come HTTP 404 o 500.
SyBox ha contattato correttamente l'indirizzo, ma il tuo server ha risposto con un errore. Controlla l'URL e consulta i log del tuo server.
Non riesco a creare un webhook, il sistema dice che non sono autorizzato.
Per creare un webhook o riattivarlo occorrono sia il permesso "Gestisci i canali" sia "Mostra il numero del contatto". Rivolgiti all'amministratore.