Webhooks

Endpoint Registration

Webhook destinations are registered via a POST to /v1/webhooks/endpoints, accepting a target URL, an event filter array, and an optional metadata object for routing context. Upon registration, Meridian immediately dispatches a verification challenge — a signed ping event that your endpoint must acknowledge with a 200 OK within 5 seconds. Endpoints that fail verification are placed in PENDING state and will not receive live events until the challenge is resolved.

Payload Signing & Verification

Every outbound webhook payload is signed using HMAC-SHA256 with a per-endpoint secret generated at registration time. The signature is transmitted in the X-Meridian-Signature-256 header as sha256=<hex_digest>. Recipients must compute the expected signature over the raw request body and compare using a constant-time equality function to prevent timing attacks. Replay protection is enforced via the X-Meridian-Timestamp header; payloads older than 300 seconds are rejected by Meridian’s ingress validators.

Retry Policy & Dead-Letter Queues

Failed deliveries — defined as any non-2xx response or a TCP timeout exceeding 10 seconds — trigger an exponential backoff retry schedule over 72 hours, with jitter applied to prevent thundering-herd congestion against recovering infrastructure. After 17 consecutive failures, the event is routed to the tenant’s dead-letter queue, accessible via GET /v1/webhooks/dlq. Events in the DLQ are retained for 7 days and can be replayed individually or in bulk once the downstream system is restored.