An overview of webhooks available for customer onboarding, card issuing, and card transaction processing flows.
Two webhook typesMost webhooks are notifications — fire-and-forget events that inform your system of something that happened.
CardAuthorizationRequestis different: it is a synchronous request that expects your response to approve or decline the transaction. See CardAuthorizationRequest for details.All card-transaction notification webhooks (
CardTransactionApproved,CardTransactionDeclined,CardTransactionReversed,CardTransactionCleared,CardTransactionRefunded) are informational: You do not need to perform an immediate credit or debit of your own in reaction to these webhooks — use them to keep your own records in sync, not to trigger money movement.
Onboarding and Account Events
Events providing real-time updates on a customer's journey through the Altery system.
| Webhook Event | Description |
|---|---|
CustomerStatusChanged | Triggered when a customer's overall status or verification status changes |
CustomerIdDocumentAdded | Triggered when an identity or support document is successfully uploaded and processed |
CustomerVerificationProcessed | Triggered when the KYC verification process is completed |
CustomerPersonalBankAccountCreated | Triggered when a personal bank account is successfully provisioned for the verified customer |
Card Lifecycle Events
Events related to card lifecycle and status changes.
| Webhook Event | Description |
|---|---|
CardIssued | Triggered when a new card is successfully issued |
CardIssuanceFailed | Triggered when card issuance fails |
CardFrozen | Triggered when a card is frozen and can no longer be used for transactions |
CardUnfrozen | Triggered when a frozen card is unfrozen and restored to active state |
CardBlocked | Triggered when a card is blocked and can no longer be used for transactions |
CardClosed | Triggered when a card is closed and permanently taken out of service |
OmnibusThresholdBreached | Triggered when the balance of an omnibus account crosses a configured threshold |
Payment Flows
Events following the transaction lifecycle from authorization through to settlement and refund.
| Webhook Event | Type | Description |
|---|---|---|
CardAuthorizationRequest | Request | Sent to approve or decline a transaction in real time. Requires a response. |
Card3DSChallengeForwarded | Notification | Triggered when a 3DS challenge is initiated and forwarded to the cardholder |
Card3DSStatusChanged | Notification | Triggered when the outcome of a 3DS session changes |
CardTransactionApproved | Notification | Triggered when a transaction is successfully authorized |
CardTransactionDeclined | Notification | Triggered when a transaction is declined at authorization |
CardTransactionReversed | Notification | Triggered when an authorized transaction is cancelled before settlement |
CardTransactionCleared | Notification | Triggered when a transaction is settled and funds are transferred |
CardTransactionRefunded | Notification | Triggered when a settled transaction is refunded to the cardholder |
Common Transaction Flows
The events above combine into three common end-to-end flows. Each flow page includes a sequence diagram of exactly which webhooks fire and in what order:
| Flow | Webhook sequence |
|---|---|
| Authorization flow | CardAuthorizationRequest → CardTransactionApproved → CardTransactionCleared |
| Reversal flow | CardAuthorizationRequest → CardTransactionApproved → CardTransactionReversed |
| Refund flow | CardAuthorizationRequest → CardTransactionApproved → CardTransactionCleared → CardTransactionRefunded |
For the less common cases (zero-amount authorizations, unmatched refunds, partial reversals, offline authorizations, etc.), see Non-Standard Transaction Scenarios.
3DSecure Authentication
For transactions requiring 3DSecure authentication with authenticationMethod: Otp, Altery triggers the Card3DSChallengeForwarded webhook. The partner is responsible for:
- Delivering the OTP code to the customer.
- Collecting the code from the customer.
- Confirming the verification via the Confirm 3DS API.
You can monitor state changes (including automatic expiration) via the Card3DSStatusChanged webhook.
Connecting to Webhooks
Currently, webhook URLs are configured during the onboarding process or by contacting Altery support. You provide the URL(s) you want to use to receive webhook events. You can use a single endpoint for all events or configure a separate URL for each event type.
[!NOTE]
This configuration process is subject to change as we introduce self-service management tools in the future.
Expected Response
For all notification webhooks, only the HTTP status code is evaluated — the response body is ignored.
| Status Code | Behavior |
|---|---|
200 | Webhook delivered successfully, no retry |
| Any non-200 | Webhook is scheduled for retry |
For CardAuthorizationRequest behavior, see CardAuthorizationRequest.
Webhook Retry Policy
By default, the webhook delivery system is configured with the following retry policy:
- Maximum Attempts: Up to 10 retry attempts are made for failed deliveries.
- Exponential Backoff: The delay between attempts increases significantly, starting from approximately 15 seconds for the first retry to almost 2 hours for the 10th attempt.
- Fresh Signatures: Each retry attempt generates a new
X-Timestampand a freshX-Signature. This ensures that delayed retries are not rejected by the 5-minute replay attack protection window.
Event Ordering
While Altery attempts to deliver webhooks as soon as they are triggered, strict ordering is not guaranteed. Network issues or delivery failures may cause a later event to be successfully delivered while an earlier event is scheduled for retry. Your system should be designed to handle events out of order, typically by using the timestamps or transaction IDs included in the payload.
Security
All webhooks are signed. See Webhook Security for signature verification instructions.