Skip to main content

​
Configuration

Meridian configures webhook endpoints during provisioning. Each event type has exactly one URL. You can point several event types at the same URL, or give each its own handler. There is no fallback between event types and no default URL, so Meridian does not deliver events for an event type with no URL configured.

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

​
Payload shape

Every body is a JSON object with two keys: the resource, and metadata. The resource key matches X-Meridian-Resource-Type in camel case, for example informationRequest. There is no other envelope.
Meridian handles empty fields differently by resource:
  • Enrollment and Information Request send every key. A field with no value is null.
  • Transaction and account leave out fields with no value.
Timestamps are always UTC with milliseconds, for example 2026-09-29T14:00:00.000Z.

​
Security

Meridian signs every webhook with HMAC SHA-256, using a Webhook API Key and Secret. Meridian issues these separately from your REST API credentials, and one pair covers every webhook event. Each request includes the following headers: To verify a request, build this string and compute its HMAC SHA-256 with your webhook secret:
  • apiKey and timestamp are the header values.
  • path is the path of your webhook URL, without the query string. For https://example.com/hooks/meridian?env=prod it is /hooks/meridian.
  • body is the raw request body, exactly as received. Verify before you parse it.
Compare the result with X-Meridian-Signature, and reject the request if it does not match or a header is missing. To guard against replayed requests, also reject a timestamp that is far from your own clock. Webhooks use the same method as Server-to-server authentication with HMAC, with two differences: the path never includes a query string, and there are no X-Meridian-Program-Id or X-Meridian-User-Id headers.

​
Delivery and retries

Meridian considers a webhook delivered when your endpoint returns an HTTP 2xx response within 10 seconds. Meridian retries any other result: a timeout, a connection error, or a non-2xx status, including 4xx and 429. Retries use exponential backoff. The wait starts at 2 seconds and doubles each time, up to 200 seconds. Meridian makes at most 10 attempts over about 12 minutes, then stops. Return a 2xx as soon as you have stored the event, and do the rest of the work afterwards. A slow response can time out and be delivered again. Webhooks are best effort. An event can occasionally be lost before the first delivery attempt, so reconcile with the GET endpoints from time to time rather than relying on webhooks alone.

​
Duplicates and ordering

You can receive the same event more than once. Retries redeliver it, and Meridian sends some events again without any change:
  • transaction_status_updated is sent every time a status is written, even when it is the same status.
  • account_status_updated is sent after any change to an account, not only a status change.
  • enrollment_status_updated can repeat with ACTIVE, for example when a feature is added.
Webhooks carry no event ID. Make your handler idempotent by deduplicating on the resource id, X-Meridian-Event-Type, status, and updatedAt. Events can also arrive out of order. Store the updatedAt you already have for each resource, and ignore an event whose updatedAt is older. For example, an Information Request moves from PROCESSING_SUBMISSION to PENDING_REVIEW to COMPLETED, but you may receive COMPLETED first.