Skip to main content

​
Configurazione del Webhook

I Webhook sono il modo in cui Meta consegna a Switchbord ogni messaggio in entrata, stato di consegna e aggiornamento dei template. Senza un Webhook configurato correttamente, la tua inbox non riceverà messaggi. Questa guida illustra i passaggi esatti per configurare i Webhook di Meta — sia che tu stia utilizzando la piattaforma hosted su app.switchbord.ai, sia un’istanza self-hosted.
Completa prima la guida Connetti WhatsApp. Ti servono un’App Meta con WhatsApp aggiunto e un WABA ID prima di configurare i Webhook.

​
Come Funziona

Quando un utente invia un messaggio al tuo numero WhatsApp, Meta chiama il tuo Webhook URL con il payload dell’evento. Switchbord:
  1. Verifica la firma usando il tuo App Secret
  2. Archivia l’envelope raw in Supabase
  3. Instrada l’evento all’inbox dell’operatore in tempo reale
Il parametro query ?w= sul Webhook URL indica a Switchbord a quale workspace appartiene l’evento. È così che funziona il multi-tenancy — ogni workspace ha un callback URL univoco.

​
Configurazione Passo Dopo Passo

1

Trova il tuo Workspace ID

In Switchbord, vai su Settings → General. Copia il tuo Workspace ID — è uno UUID simile a a1b2c3d4-....Lo aggiungerai al callback URL del Webhook nel passaggio successivo.
2

Configura il callback URL in Meta

In Meta for Developers, apri la tua app e vai su:WhatsApp → Configuration → WebhookClicca su Edit e imposta:
  • Callback URL:
    Sostituisci {your-workspace-id} con lo UUID del passaggio precedente. Per le istanze self-hosted, sostituisci api.switchbord.ai con il tuo domain API.
  • Verify token: Una stringa a tua scelta. La inserirai anche nelle Settings di Switchbord. Usa una stringa casuale — ad esempio, openssl rand -hex 20 in un terminale.
Clicca su Verify and save. Meta invierà immediatamente una richiesta di challenge al tuo callback URL. Switchbord risponde automaticamente se l’URL e il verify token sono corretti.
Se la verifica fallisce, controlla che:
  • Il callback URL sia raggiungibile da internet (non localhost)
  • Il parametro ?w= contenga esattamente il tuo workspace UUID
  • Il verify token corrisponda a quello impostato nelle Settings di Switchbord
3

Sottoscrivi i campi del Webhook

Dopo aver salvato il callback URL, scorri fino a Webhook fields e clicca su Manage.Sottoscrivi i seguenti campi:Clicca su Done.
Ti serve solo messages per il funzionamento base dell’inbox. Campi aggiuntivi come message_template_status_update possono essere aggiunti in seguito per le notifiche di sincronizzazione dei template.
4

Imposta il verify token in Switchbord

In Switchbord, vai su Settings → Provider → Channel.Inserisci il Verify token — la stessa stringa usata nella configurazione del Webhook Meta.Salva le impostazioni.
5

Imposta il signing secret del Webhook

Il signing secret è il tuo Meta App Secret. Switchbord lo usa per verificare l’header X-Hub-Signature-256 su ogni Webhook in entrata — se la firma non corrisponde, il payload viene rifiutato.Trova il tuo App Secret:In Meta for Developers, apri la tua app → App Settings → Basic.Clicca su Show vicino a App secret e copia il valore.In Switchbord, vai su Settings → Provider → Channel e inserisci l’App Secret come Webhook signing secret.
Non esporre mai il tuo App Secret in codice client-side, file di variabili d’ambiente committati in git, o output di log. È un secret esclusivamente server-side. In Switchbord è archiviato nel Supabase Vault.
6

Verifica che la configurazione funzioni

Invia un messaggio di test al tuo numero WhatsApp da un telefono reale. Poi:
  1. Apri Switchbord → Inbox — il messaggio dovrebbe apparire in pochi secondi
  2. Apri Switchbord → Operations — cerca una voce Webhook recente con stato verified
Se il messaggio non appare:
  • Controlla la pagina Operations per Webhook rifiutati (uno stato rosso indica che la verifica della firma è fallita)
  • Conferma che l’App Secret nelle Settings corrisponda a quello in Meta App Settings → Basic
  • Conferma che il tuo numero WhatsApp sia in Live mode (non Development) — la modalità Development riceve messaggi solo dai tester

​
Perché il Parametro ?w= è Importante

Switchbord è multi-tenant. Più workspace possono condividere un unico deployment API, ognuno con il proprio numero WhatsApp e le proprie credenziali. Il parametro ?w= è il modo in cui Switchbord instrada il Webhook in entrata al workspace corretto. Senza di esso, l’ingress del Webhook non può determinare a quale workspace assegnare l’evento e rifiuterà il payload. Ogni workspace ottiene il proprio callback URL:
Ciò significa che se gestisci più numeri WhatsApp su workspace diversi, ogni workspace ha un Webhook URL distinto in Meta — anche se tutti puntano allo stesso host api.switchbord.ai.

​
Riferimento Credenziali

​
Risoluzione dei Problemi

La verifica del Webhook fallisce immediatamente
  • Assicurati che l’API sia raggiungibile pubblicamente. localhost non funzionerà — usa un tunnel (ngrok, Cloudflare Tunnel) per lo sviluppo locale.
  • Il callback URL deve includere il parametro ?w= con un workspace UUID valido.
  • Il verify token in Meta deve corrispondere esattamente a quello nelle Settings di Switchbord.
I messaggi non appaiono nell’inbox
  • Controlla Operations per i rifiuti del Webhook. Un errore signature_mismatch significa che l’App Secret in Switchbord non corrisponde a quello in Meta.
  • Assicurati che il campo messages sia sottoscritto nel field manager del Webhook di Meta.
  • Conferma che il numero di telefono sia in Live mode, non in Development mode.
Errori di consegna intermittenti
  • Meta ritenta i Webhook falliti. Se la tua API era temporaneamente irraggiungibile, gli eventi verranno replicati automaticamente.
  • Controlla la pagina Operations per una coda di replay in attesa.
  • Consulta il Runbook Operations per le procedure di escalation.

​
Guide Collegate