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

# Webhook

> Panoramica sugli eventi webhook in ingresso — a cosa servono, dove configurarli e come si inseriscono nella superficie di integrazione di Switchbord.

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](/it/operations/webhooks) e [Configurazione dei webhook](/it/platform/webhook-setup).

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

<CardGroup cols={2}>
  <Card title="Endpoint generato" icon="link">
    Ogni configurazione di webhook ottiene il proprio URL sotto `/api/v1/inbound-webhooks/{slug}` — nessun segreto condiviso tra le configurazioni.
  </Card>

  <Card title="Mappatura del modello" icon="table-cells">
    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.
  </Card>
</CardGroup>

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

<Warning>
  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](/it/guides/webhook-dry-run-rollout) per lo stato attuale e cosa fare se hai bisogno di invii in produzione oggi.
</Warning>

## 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](/it/api-reference/inbound-webhooks).

## 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](/it/features/inbox) in primo luogo. È un passaggio di configurazione unico trattato in [Configurazione dei webhook](/it/platform/webhook-setup), e il modello operativo che c'è dietro (memorizzazione della busta, verifica, replay) è documentato in [Operazioni sui webhook](/it/operations/webhooks).

## Vedi anche

* [Configurazione dei webhook](/it/platform/webhook-setup) — configurare Meta per consegnare eventi WhatsApp alla tua area di lavoro.
* [Operazioni sui webhook](/it/operations/webhooks) — il modello interno della busta, il monitoraggio e gli strumenti di replay.
* [Webhook in ingresso](/it/api-reference/inbound-webhooks) — il riferimento completo su autenticazione e mappatura per le tue integrazioni.
* [Rollout dry-run dei webhook in ingresso](/it/guides/webhook-dry-run-rollout) — stato attuale della promozione e passaggi di test sicuri.