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

> Configura webhook inbound protetti da HMAC che mappano eventi esterni verso invii di template transazionali.

I webhook inbound consentono a un workspace di ricevere eventi da sistemi esterni e mapparli nel contratto di invio di template transazionale di Switchbord.

## Impostazioni predefinite di sicurezza

Le nuove configurazioni webhook sono disabilitate e in dry-run per impostazione predefinita. Un dry-run registra l'esecuzione inbound, verifica la firma, valida la mappatura e memorizza la richiesta transazionale mappata senza accodare un invio effettivo.

I segreti vengono generati una sola volta. Switchbord memorizza solo un hash SHA-256 e un breve prefisso per la visualizzazione. Le risposte di elenco non includono mai il segreto grezzo. Dopo la creazione, non inviare mai il segreto grezzo a Switchbord; usalo solo per produrre le firme delle richieste.

## Endpoint

Ogni configurazione ottiene un URL generato:

```text theme={null}
POST /api/v1/inbound-webhooks/{slug}
```

L'endpoint risolve il workspace e la configurazione del webhook dallo slug dell'URL. I campi del payload non vengono mai considerati attendibili per la risoluzione del tenant.

## Autenticazione

Le richieste devono includere una firma HMAC con timestamp calcolata sul corpo grezzo esatto della richiesta. Non includere il segreto webhook grezzo negli header, nei parametri di query o nel payload.

```text theme={null}
X-Switchbord-Signature: t=<timestamp unix in secondi>,v1=<hmac sha256 hex>
Idempotency-Key: id-evento-esterno-opzionale
```

L'HMAC `v1` firma `{timestamp}.{rawBody}` con il segreto one-time generato alla creazione del webhook. I timestamp devono trovarsi entro cinque minuti dall'orologio di Switchbord per ridurre il rischio di replay. Sono accettate più voci `v1`, così i mittenti possono ritentare durante la rotazione delle chiavi, ma almeno una deve corrispondere.

Esempio di generazione della firma:

```ts theme={null}
import { createHash, createHmac } from "node:crypto";

const timestamp = Math.floor(Date.now() / 1000);
const secretHash = createHash("sha256").update(secret).digest("hex");
const digest = createHmac("sha256", secretHash)
  .update(`${timestamp}.${rawBody}`)
  .digest("hex");
const signature = `t=${timestamp},v1=${digest}`;
```

La verifica della firma usa un confronto a tempo costante (timing-safe) e avviene prima della mappatura o dell'accodamento.

## Mappatura

Il builder in Settings è il modo consigliato per creare le mappature. Carica i template Utility approvati, mostra le variabili body/button/header di cui ogni template ha bisogno e ti consente di mappare ogni campo da un percorso del payload, un valore letterale o un valore JSON.

Le mappature a runtime supportano valori dot-path legacy ed espressioni esplicite:

```json theme={null}
{
  "to": "path:customer.phone",
  "templateName": "literal:payment_receipt_document",
  "templateLocale": "literal:it",
  "externalId": "path:receipt.id",
  "parameters.header.document.link": "path:receipt.pdf",
  "parameters.header.document.filename": "literal:receipt.pdf",
  "parameters.body.1": "path:customer.first_name",
  "parameters.body.2": "path:receipt.number"
}
```

Prefissi delle espressioni:

| Prefisso        | Significato                                   |
| --------------- | --------------------------------------------- |
| `path:`         | Risolve un dot path dal payload JSON inbound. |
| `literal:`      | Usa il testo dopo il prefisso come valore.    |
| `json:`         | Analizza il testo dopo il prefisso come JSON. |
| nessun prefisso | Ricerca dot-path legacy dal payload inbound.  |

I target delle mappature non possono contenere `__proto__`, `prototype` o `constructor`. Switchbord rifiuta i target non sicuri prima dell'anteprima o dell'elaborazione del webhook.

I valori `templateName` e `templateLocale` configurati sovrascrivono i valori mappati. Le nuove configurazioni create tramite Settings sono limitate al template Utility approvato selezionato.

## Log delle esecuzioni

Ogni richiesta ricevuta per una configurazione abilitata registra un'esecuzione con header redatti, metadata sulla forma del payload, diagnostica della richiesta mappata sanificata, stato ed errori. I payload grezzi del cliente, i numeri di telefono dei destinatari e i valori delle variabili del template non vengono memorizzati nei log delle esecuzioni per impostazione predefinita. Le firme non valide vengono registrate come esecuzioni fallite e restituiscono `401`, ma non riservano chiavi di idempotenza verificate.

I possibili stati di esecuzione includono `verified`, `dry_run`, `queued`, `failed` e `skipped_duplicate`.

## Limitazione attuale

La base runtime può eseguire il servizio di invio di template transazionale quando una configurazione è abilitata, ma le configurazioni create tramite Settings sono attualmente forzate in modalità dry-run disabilitata e non possono essere promosse tramite l'API pubblica di Settings. Una richiesta firmata verso una configurazione disabilitata restituisce `404 webhook_not_found_or_disabled`. La promozione live è bloccata a livello server finché non viene rilasciato un flusso di promozione verificato dai log delle esecuzioni. Usa [Invii di template transazionali](/it/api-reference/transactional-template-sends) per gli invii in produzione oggi.

## Guide di integrazione

* [Link della ricevuta di pagamento tramite bottone URL](/it/guides/receipt-link-webhook)
* [Ricevuta PDF tramite header DOCUMENT](/it/guides/pdf-receipt-webhook)
* [Rollout dry-run per webhook inbound](/it/guides/webhook-dry-run-rollout)