Skip to main content
Switchbord utilizza i webhook in due direzioni. Meta invia webhook verso Switchbord per ogni messaggio WhatsApp, stato di consegna e aggiornamento di modello — è così che la tua posta in arrivo rimane aggiornata in tempo reale. Separatamente, Switchbord può ricevere webhook dai tuoi sistemi esterni (una piattaforma di prenotazione, un elaboratore di pagamenti, un CRM) e trasformarli in invii WhatsApp in uscita. Questa pagina copre il secondo tipo — la superficie di integrazione che gli operatori configurano. Questa è l’introduzione più leggera, orientata all’operatore. Per il contratto tecnico completo — schema della busta, formato della firma HMAC, strumenti di replay — consulta Operazioni sui webhook e Configurazione dei webhook.

​
A cosa servono i webhook in ingresso

Se un sistema esterno deve attivare un messaggio WhatsApp quando succede qualcosa altrove — viene generata una ricevuta, un ordine viene spedito, viene prenotato un appuntamento — non devi scrivere codice di integrazione personalizzato. Configuri un endpoint webhook in Switchbord, mappi i campi dell’evento esterno alle variabili di un modello approvato, e il sistema esterno effettua una POST verso quell’endpoint ogni volta che l’evento si verifica.

Endpoint generato

Ogni configurazione di webhook ottiene il proprio URL sotto /api/v1/inbound-webhooks/{slug} — nessun segreto condiviso tra le configurazioni.

Mappatura del modello

Il builder in Impostazioni carica i tuoi modelli Utility approvati e ti permette di mappare ogni variabile da un campo del payload, un valore letterale o un valore JSON.

​
Configurarne uno

I webhook in ingresso si configurano da Impostazioni → Integrazioni → Webhook e API:
  1. Fai clic su Crea webhook.
  2. Seleziona un modello Utility approvato.
  3. Mappa le variabili del modello ai campi nel payload del tuo sistema esterno.
  4. Incolla un payload di esempio ed esegui l’anteprima dry-run per confermare che la mappatura si risolva correttamente — questo avviene interamente nel browser e non invia mai un messaggio.
  5. Crea il webhook una volta superata l’anteprima. Il segreto di firma viene mostrato una sola volta — copialo immediatamente nell’archivio segreti del tuo sistema esterno, poiché da quel momento Switchbord memorizza solo un hash.
Le nuove configurazioni di webhook vengono create disabilitate e in modalità dry-run per impostazione predefinita, come misura di sicurezza. Un dry-run verifica la firma e valida la mappatura senza accodare un invio in produzione. La promozione in produzione per i webhook creati da Impostazioni è attualmente bloccata a livello server in attesa di controlli di promozione verificati — consulta la guida al rollout dry-run dei webhook per lo stato attuale e cosa fare se hai bisogno di invii in produzione oggi.

​
Autenticazione delle richieste

Ogni richiesta deve portare una firma HMAC con timestamp calcolata sul corpo grezzo della richiesta, generata con il segreto temporaneo mostrato al momento della creazione. Switchbord la verifica con un confronto a tempo costante prima di toccare la mappatura o accodare qualsiasi cosa. Il formato completo della firma e un esempio di codice funzionante si trovano in Webhook in ingresso.

​
I webhook di Meta (l’altra direzione)

Separatamente, il tuo numero WhatsApp richiede che Meta sia configurato per inviare i suoi webhook a Switchbord — questo è ciò che fa apparire i messaggi nella tua Posta in arrivo in primo luogo. È un passaggio di configurazione unico trattato in Configurazione dei webhook, e il modello operativo che c’è dietro (memorizzazione della busta, verifica, replay) è documentato in Operazioni sui webhook.

​
Vedi anche