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

# Operações de Webhook

> Contratos de ingestão, normalização, replay e monitoramento.

# Operações de Webhook

Webhooks são o plano de controle. Esta página é o modelo operacional de webhook publicado para a plataforma.

## Princípios-Chave

* **Verifique cada entrega.** A Meta usa `X-Hub-Signature-256`; hooks de parceiros podem usar HMAC ou tokens estáticos.
* **Persista os envelopes brutos.** Mantenha headers, hash do body, parâmetros de query e metadados de tenant/provider com políticas de retenção.
* **Normalize para famílias de eventos conhecidas.** Use `provider.message.inbound`, `.status`, `.template.updated`, `.conversation.updated`, etc.
* **Faça replay com segurança.** Cada replay cria um novo registro de tentativa sem alterar o envelope original.
* **Trate duplicados.** Deduplique pelo delivery ID, mas mantenha o timestamp mais recente e permita replay manual quando ocorrerem melhorias legítimas.

## Modelo de Envelope

Cada envelope registra:

* tenant, provider, escopo do provider (WABA ou número de telefone)
* família do evento, ID de evento externo, delivery ID
* status de verificação e normalização
* headers/parâmetros de query/hash do body/body bruto
* status de resposta e metadados de replay

## Endpoints Operacionais

* `GET /internal/webhooks` – filtra por tenant, tipo, cursor.
* `GET /internal/webhooks/:id` – inspeciona headers, body, status do evento normalizado.
* `GET /internal/webhook-rejections`, `/internal/webhook-rejections/:id` – forense.
* `POST /internal/webhooks/:id/replay` – reprocessa após aprovação do operador.
* `GET /internal/runtime` – profundidade de fila, atraso dos workers, tendências de backlog.

## Monitoramento

* Latência: meta de mediana `abaixo de 250 ms`, com `menos de 1%` das requisições acima de `1 s`.
* Contagem de rejeições e replays.
* Profundidade de fila e heartbeat dos workers.
* Taxas de falha na validação de templates.
* Violações de guardrail de pair-rate e throughput.

## Runbook

Consulte [Runbook de Operações](/pt-BR/operations/runbook) para etapas de resposta a incidentes, incluindo indisponibilidade de webhook, violação de rate limit e falhas de campanha/journey.