> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Learn how Meridian delivers real-time event notifications to your system via HTTP POST webhooks, including configuration, security, and retry behavior.

## Configuration

<Info>
  Meridian configures webhook endpoints during provisioning.
</Info>

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:

| Header                 | Description                                                          |
| :--------------------- | :------------------------------------------------------------------- |
| `X-Meridian-Api-Key`   | Issued by Meridian, specifically for Webhooks                        |
| `X-Meridian-Timestamp` | Current time in milliseconds<br />(within 60 seconds of the request) |
| `X-Meridian-Signature` | HMAC SHA-256 signature                                               |

Validate the signature on every inbound request before processing the payload. Use the same canonical string construction described in [Authentication](/products/retail-va/authentication#constructing-the-signature).

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