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-TypetransactionRoutes the payload to the correct resource handler
X-Meridian-Event-Typeprocessing_status_updatedSelects the specific event parser for that resource
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 Authentication.

​
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 transaction. Only overwrite when the incoming payload reflects a newer state or a valid progression. Log non-2xx responses and return as fast as possible; even short delays may trigger retries that redeliver the same event.