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

> Ingress contracts, normalization, replay, and monitoring.

# Webhook Operations

Webhooks are the control plane. This page is the published webhook operating model for the platform.

## Key Principles

* **Verify every delivery.** Meta uses `X-Hub-Signature-256`; partner hooks may use HMAC or static tokens.
* **Persist raw envelopes.** Retain headers, body hash, query params, and tenant/provider metadata with retention policies.
* **Normalize to known event families.** Use `provider.message.inbound`, `.status`, `.template.updated`, `.conversation.updated`, etc.
* **Replay safely.** Every replay creates a new attempt record without mutating the original envelope.
* **Handle duplicates.** Deduplicate by delivery ID but keep the latest timestamp and allow manual replay when legitimate improvements occur.

## Envelope Model

Each envelope records:

* tenant, provider, provider scope (WABA or phone number)
* event family, external event ID, delivery ID
* verification & normalization status
* headers/query params/body hash/raw body
* response status and replay metadata

## Operational Endpoints

* `GET /internal/webhooks` – filter by tenant, type, cursor.
* `GET /internal/webhooks/:id` – inspect headers, body, normalized event status.
* `GET /internal/webhook-rejections`, `/internal/webhook-rejections/:id` – forensics.
* `POST /internal/webhooks/:id/replay` – reprocess after operator approval.
* `GET /internal/runtime` – queue depths, worker lag, backlog trends.

## Monitoring

* Latency: target median `under 250 ms`, with `under 1%` of requests above `1 s`.
* Rejections & replay counts.
* Queue depth and worker heartbeat.
* Template validation failure rates.
* Pair-rate and throughput guardrail violations.

## Runbook

See [Operations Runbook](/operations/runbook) for incident response steps, including webhook outage, rate-limit breach, and campaign/journey failures.