Webhook
Aggiornato il
Dove: Impostazioni > Integrazioni > Webhook
A cosa serve:
"Inoltra gli eventi in arrivo al tuo server." SyBox invia una copia di ogni evento WhatsApp selezionato a un URL del tuo server, in tempo reale. I webhook supportano esclusivamente i numeri WhatsApp. Gli eventi di Messenger, Instagram, Telegram, email e SMS non vengono inoltrati.
Chi può accedervi: l'amministratore principale e i membri del team con il permesso "Manage WhatsApp numeri". Per creare un webhook o riattivarne uno in pausa, ti serve 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 che hai inviato è stato inviato, consegnato, letto o non è andato a buon fine.
- "Reazione": un cliente ha reagito a un messaggio.
- "Trascrizione vocale" (opzione aggiuntiva): i messaggi vocali vengono trattenuti per un breve momento, fino a circa due minuti, per poter inviare anche il testo trascritto. È disattivata a meno che non la abiliti.
- Vai su Impostazioni > Integrazioni > Webhook.
- Fai clic 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 locali o private non sono accettati.
- In "Eventi", attiva almeno un evento. "Messaggio in arrivo" è attivo per impostazione predefinita.
- Facoltativo: attiva "Trascrizione vocale" per ricevere i messaggi vocali con la trascrizione del testo.
- In "Numeri", mantieni selezionato "Tutti i numeri" per includere ogni numero WhatsApp. Oppure disattivalo e seleziona solo i numeri che ti interessano.
- Fai clic su Salva.
- Una finestra mostra la "Chiave di firma". "Copiala ora — viene mostrata una sola volta." Salvala sul tuo server.
Dettagli sull'inoltro degli eventi:
- Ogni notifica usa lo stesso formato dei webhook WhatsApp nativi di Meta.
- Ogni richiesta viene firmata con la tua chiave di firma nello stesso modo in cui Meta firma i propri webhook. Se il tuo server valida già le notifiche di Meta, può convalidare quelle di SyBox usando la chiave segreta di SyBox.
- Se il tuo server non risponde con esito positivo, SyBox riprova diverse volte a intervalli crescenti per circa un'ora. Trascorso questo tempo, la notifica dell'evento viene ignorata.
- Lo stesso evento può talvolta essere recapitato due volte, ad esempio dopo un timeout. Il tuo server deve essere in grado di gestire i duplicati.
- SyBox non include un pulsante dedicato per l'invio di test. Per verificarne il funzionamento:
- Assicurati che il webhook sia attivo e includa il numero che intendi utilizzare.
- Invia un messaggio WhatsApp a quel numero da un altro telefono.
- Torna in Impostazioni > Integrazioni > Webhook. La scheda mostra l'ultima risposta ricevuta dal tuo server, con relativo orario. Una risposta corretta (come "HTTP 200") compare in verde. Un errore appare in rosso. "Ultima consegna: mai" significa che nessun evento è stato ancora inoltrato.
- Fai clic su Modifica per cambiare nome, URL, eventi o numeri associati.
- Per aggiornare la chiave segreta, inseriscine una nuova in "Chiave di firma". Lasciala vuota per mantenere quella attuale ("Lascia vuoto per mantenere la chiave attuale").
- Fai clic su Attiva / Disattiva per metterlo in pausa. Gli eventi generati mentre è in pausa rimangono in coda: se lo riattivi a breve, verranno recapitati.
- Fai clic su Elimina, quindi conferma l'operazione con "Eliminare questo webhook?".
Regole e avvisi:
- Nome e URL di destinazione sono obbligatori, e deve essere selezionato almeno un evento. In caso contrario, comparirà l'avviso "Dati incompleti".
- Un URL che non sia https pubblico viene rifiutato con il messaggio "Un indirizzo https pubblico raggiungibile".
Ho perso la chiave di firma.
Non può essere mostrata nuovamente. Modifica il webhook, inserisci una nuova chiave personalizzata nel campo "Chiave di firma", salva la modifica e imposta la nuova chiave sul tuo server.
Il mio webhook non riceve alcuna notifica.
Verifica questi quattro punti: (1) Il webhook è attivo. (2) È selezionato almeno un evento. (3) È associato al numero WhatsApp corretto o a "Tutti i numeri". (4) Il tuo spazio di lavoro ha effettivamente un numero WhatsApp connesso, poiché i webhook gestiscono unicamente gli eventi WhatsApp. Controlla poi il risultato dell'ultimo inoltro sulla scheda.
La scheda mostra un errore in rosso come HTTP 404 o 500.
SyBox ha contattato il tuo indirizzo, ma il tuo server ha restituito un codice di errore. Verifica l'indirizzo e consulta i log del tuo server.
Non riesco a creare un webhook, il sistema dice che non dispongo dei permessi.
Per creare un webhook o riattivarlo sono necessari sia il permesso "Manage WhatsApp numeri" che "Mostra il numero del contatto". Rivolgiti al tuo amministratore.