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. Both transaction events carry the same Virtual Account Transaction payload: created fires when a new transaction is initiated, and updated fires when the status of an existing transaction changes. Read the headers first, then deserialize the body with the matching webhook schema.

​
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.

​
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.