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

# Overview

> Learn how Meridian Accounts delivers webhook notifications, including security, retries, and delivery behavior.

## Configuration

Meridian configures webhook endpoints during provisioning.

You can configure a separate URL for each webhook event type. If your integration needs different handling per event, set each webhook URL to the appropriate handler endpoint.

## 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 schema to use.

| Header                     | Example values                                                | Use                                                 |
| :------------------------- | :------------------------------------------------------------ | :-------------------------------------------------- |
| `X-Meridian-Resource-Type` | `enrollment`, `information_request`, `transaction`, `account` | Routes the payload to the correct resource handler  |
| `X-Meridian-Event-Type`    | See the event types table below                               | Selects the specific event parser for that resource |

| Resource              | Event types                                                         |
| :-------------------- | :------------------------------------------------------------------ |
| `enrollment`          | `enrollment_created`, `enrollment_status_updated`                   |
| `information_request` | `information_request_created`, `information_request_status_updated` |
| `transaction`         | `transaction_created`, `transaction_status_updated`                 |
| `account`             | `account_created`, `account_status_updated`                         |

Read these headers first, then deserialize the request body with the matching webhook schema. This lets your handler reject unexpected combinations early and keeps your routing logic aligned with the payload shape.

## Security

Webhook requests use HMAC SHA-256 with a dedicated Webhook API Key and Secret. Each request includes the following headers:

| Header                 | Description                                                    |
| :--------------------- | :------------------------------------------------------------- |
| `X-Meridian-Api-Key`   | Issued by Meridian for webhook delivery                        |
| `X-Meridian-Timestamp` | Current time in milliseconds, 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 [Server-to-server authentication with HMAC](/products/meridian-accounts/guides/server-to-server-authentication-with-hmac).

## 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` response, Meridian retries using exponential backoff, up to **6 attempts over 24 hours**.

Because retries can produce duplicate deliveries, your webhook handler should be idempotent.

Treat every webhook as potentially arriving out of order. Store the status and timestamp you already know for each enrollment, Information Request, account, or transaction. Only overwrite when the incoming payload reflects a newer state or a valid progression (for example, `PENDING` → `ACTION_REQUIRED` → `COMPLETED`).

Log non-`2xx` responses and return as fast as possible; even short delays may trigger retries that redeliver the same event.