> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configurazione del Webhook

> Configura Meta per inviare gli eventi WhatsApp alla tua istanza Switchbord — callback URL, signing secret, verify token e sottoscrizioni ai campi.

# 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.

<Warning>
  Completa prima la guida [Connetti WhatsApp](/it/platform/connect-whatsapp). Ti servono un'App Meta
  con WhatsApp aggiunto e un WABA ID prima di configurare i Webhook.
</Warning>

***

## 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Configura il callback URL in Meta">
    In [Meta for Developers](https://developers.facebook.com), apri la tua app e vai su:

    **WhatsApp → Configuration → Webhook**

    Clicca su **Edit** e imposta:

    * **Callback URL:**

      ```
      https://api.switchbord.ai/webhooks/meta?w={your-workspace-id}
      ```

      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.

    <Tip>
      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
    </Tip>
  </Step>

  <Step title="Sottoscrivi i campi del Webhook">
    Dopo aver salvato il callback URL, scorri fino a **Webhook fields** e clicca su **Manage**.

    Sottoscrivi i seguenti campi:

    | Campo      | Scopo                                                       |
    | ---------- | ----------------------------------------------------------- |
    | `messages` | Messaggi in entrata, stati di consegna, conferme di lettura |

    Clicca su **Done**.

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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.
  </Step>

  <Step title="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](https://developers.facebook.com), 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**.

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="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
  </Step>
</Steps>

***

## 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:

```
https://api.switchbord.ai/webhooks/meta?w=<workspace-uuid>
```

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

| Impostazione           | Dove trovarla                                                    | Dove inserirla                                                     |
| ---------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------ |
| Callback URL           | Costruito a partire dal tuo workspace ID (vedi sopra)            | Meta App → WhatsApp → Configuration → Webhook                      |
| Verify token           | Lo generi tu                                                     | Sia in Meta (webhook config) che in Switchbord Settings → Provider |
| Webhook signing secret | Meta App → App Settings → Basic → App Secret                     | Switchbord Settings → Provider → Channel                           |
| WABA ID                | Meta Business Settings → Accounts → WhatsApp Accounts → Settings | Switchbord Settings → Provider → Channel                           |
| Phone Number ID        | Meta App → WhatsApp → API Setup                                  | Switchbord Settings → Provider → Channel                           |
| System User token      | Meta Business Settings → System Users                            | Switchbord Settings → Provider → Channel                           |

***

## 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](/it/operations/runbook) per le procedure di escalation.

***

## Guide Collegate

* [Connetti WhatsApp](/it/platform/connect-whatsapp) — configurazione completa delle credenziali, incluso WABA ID, numero di telefono e System User token
* [Configurazione delle Credenziali Meta](/it/operations/meta-credential-setup) — guida dettagliata per i System User token e la configurazione del Business Portfolio
* [Operazioni sui Webhook](/it/operations/webhooks) — modello interno del Webhook, schema dell'envelope e strumenti di replay