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 theX-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.
Security
Webhook requests use HMAC SHA-256 with a dedicated Webhook API Key and Secret. Each request includes the following headers:
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 HTTP2xx response within 10 seconds. If the request times out or returns a non-2xx response, Meridian retries using exponential backoff starting at 2 seconds, up to 10 attempts.
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, DRAFT → PENDING_REVIEW → COMPLETED).
Log non-2xx responses and return as fast as possible; even short delays may trigger retries that redeliver the same event.