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

# Operazioni sui Webhook

> Contratti di ingresso, normalizzazione, replay e monitoraggio.

# Operazioni sui Webhook

I Webhook sono il control plane. Questa pagina è il modello operativo pubblicato per la gestione dei webhook della piattaforma.

## Principi Chiave

* **Verifica ogni delivery.** Meta usa `X-Hub-Signature-256`; i hook dei partner possono usare HMAC o token statici.
* **Persisti gli envelope grezzi.** Conserva header, hash del body, parametri di query e metadati tenant/provider secondo le policy di retention.
* **Normalizza verso famiglie di eventi conosciute.** Usa `provider.message.inbound`, `.status`, `.template.updated`, `.conversation.updated`, ecc.
* **Esegui il replay in sicurezza.** Ogni replay crea un nuovo record di tentativo senza modificare l'envelope originale.
* **Gestisci i duplicati.** Deduplica per delivery ID ma mantieni il timestamp più recente e consenti il replay manuale quando si verificano miglioramenti legittimi.

## Modello di Envelope

Ogni envelope registra:

* tenant, provider, ambito del provider (WABA o numero di telefono)
* famiglia dell'evento, ID evento esterno, delivery ID
* stato di verifica e normalizzazione
* header/parametri di query/hash del body/body grezzo
* stato della risposta e metadati di replay

## Endpoint Operativi

* `GET /internal/webhooks` – filtra per tenant, tipo, cursore.
* `GET /internal/webhooks/:id` – ispeziona header, body, stato dell'evento normalizzato.
* `GET /internal/webhook-rejections`, `/internal/webhook-rejections/:id` – analisi forense.
* `POST /internal/webhooks/:id/replay` – riprocessa dopo l'approvazione dell'operatore.
* `GET /internal/runtime` – profondità delle code, lag dei worker, tendenze del backlog.

## Monitoraggio

* Latenza: obiettivo mediana `sotto i 250 ms`, con `meno dell'1%` delle richieste sopra `1 s`.
* Conteggi di rejection e replay.
* Profondità della coda e heartbeat dei worker.
* Tassi di fallimento della validazione dei template.
* Violazioni dei guardrail su pair-rate e throughput.

## Runbook

Vedi [Operations Runbook](/it/operations/runbook) per i passaggi di risposta agli incidenti, inclusi interruzione dei webhook, superamento dei rate-limit e fallimenti di campagne/journey.