Skip to main content

​
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.
HeaderExample valuesUse
X-Meridian-Resource-Typeenrollment, information_request, transaction, accountRoutes the payload to the correct resource handler
X-Meridian-Event-TypeSee the event types table belowSelects the specific event parser for that resource
ResourceEvent types
enrollmentenrollment_created, enrollment_status_updated
information_requestinformation_request_created, information_request_status_updated
transactiontransaction_created, transaction_status_updated
accountaccount_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:
HeaderDescription
X-Meridian-Api-KeyIssued by Meridian for webhook delivery
X-Meridian-TimestampCurrent time in milliseconds, within 60 seconds of the request
X-Meridian-SignatureHMAC 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.

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