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 10 seconds. Meridian retries any other outcome: a timeout, a connection error, or a non-2xx status, including 4xx. Retries use exponential backoff starting at 2 seconds and doubling each time, for up to 10 attempts over roughly 12 minutes. After the final attempt, Meridian does not deliver the event again automatically. The virtual_account_transaction_created event is the exception. Meridian sends it once, on a best-effort basis, and does not retry it. Treat the updated event as the authoritative record of a transaction’s outcome. 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.