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.

​
Event routing

Use the X-Meridian-Resource-Type and X-Meridian-Event-Type headers to identify the webhook before you parse the body. These headers tell you which resource the event belongs to and which specific event occurred. All three events carry the same Payment Link payload, so read the headers first to tell them apart, then deserialize the body with the webhook schema. Other status transitions, including PROCESSING, FAILED, EXPIRED, LOCKED, and INACTIVE, do not emit a webhook.

​
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: Validate the signature on every inbound request before processing the payload. Use the same canonical string construction described in Authentication, with one difference: the signature covers the path only of your webhook URL, not its query string. If your endpoint URL includes query parameters, exclude them when rebuilding the canonical string, or the signature will not match. You decide the acceptable timestamp age. Meridian stamps X-Meridian-Timestamp when it sends the webhook and does not enforce a window on its own deliveries, so choose a tolerance that suits your infrastructure. Meridian rejects inbound API requests more than 10 seconds old, which is a reasonable reference point, but retries mean a redelivered webhook can legitimately arrive much later than its original timestamp.
Do not reject a webhook solely because its timestamp is old. Meridian retries for up to 10 attempts with doubling intervals, so a valid retry can arrive minutes after the event.

​
Delivery and retries

Meridian considers a webhook delivered when your endpoint returns an HTTP 2xx response. If the request times out or returns a non-2xx status, Meridian retries using exponential backoff — the first retry is after 2 seconds and the interval doubles each time, up to 10 attempts. 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.