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, withunder 1%of requests above1 s. - Rejections & replay counts.
- Queue depth and worker heartbeat.
- Template validation failure rates.
- Pair-rate and throughput guardrail violations.