Skip to main content

​
Configuration

Meridian configures webhook endpoints during provisioning.
You can register separate URLs for Sandbox and production — Meridian delivers all events for a given environment to a single endpoint. If you need to route events differently, your handler must direct them based on the event headers.

​
Security

Webhook requests use the same HMAC SHA-256 scheme as the REST API, but with a dedicated Webhook API Key and Secret issued separately from your REST API credentials. Each request includes the following headers:
HeaderDescription
X-Meridian-Api-KeyIssued by Meridian, specifically for Webhooks
X-Meridian-TimestampCurrent time in milliseconds
(within 60 seconds of the request)
X-Meridian-SignatureHMAC SHA-256 signature
Validate the signature on every inbound request before processing the payload. Use the same canonical string construction described in Authentication.

​
Delivery and retries

Meridian considers a webhook delivered when your endpoint returns an HTTP 2xx response within 30 seconds. If the request times out or returns a non-2xx status, Meridian retries using exponential backoff — up to 6 attempts over 24 hours. Because retries can result in duplicate deliveries, your webhook handler should be idempotent — processing the same event more than once should produce the same outcome.