Alviere POSTs webhook events to your configured URL whenever something meaningful happens on the account — KYC state changes, transactions settle, cards are issued, and so on.

Delivery

Each event is delivered as a JSON POST to your configured URL. Return any 2xx within 10 seconds to acknowledge receipt. Anything else — a non-2xx response, a timeout, or a network error — triggers a retry with the same event_uuid and an incremented event_retry counter.

Headers

Signature verification

Build the signing string as {webhook_id}.{webhook_timestamp}.{compact_body}, where compact_body is the raw request body with all insignificant JSON whitespace removed. Compute HMAC-SHA256(secret, signing_string), hex-encode it, and compare against Alviere-Signature using a constant-time comparison. Reject the request if the signatures don't match or the timestamp is more than a few minutes old.

Envelope

Every event body shares the same envelope — event_uuid, event_type, event_version, event_date, event_retry, business_account_uuid, program_uuid — plus an entity field whose shape depends on the event type. See each event below.