Webhooks & Callback Notifications

This page covers the webhook and callback mechanisms currently available on the platform, the security pattern they follow, and what to expect as the event catalog grows.

📘

Scope of this page: two callback mechanisms are available today — 3-D Secure OTP delivery, and certificate expiry reminders. Both are documented in full below. For other event types, see Tracking other events below.

Callback URLs are independent of your mTLS certificate

Every other page in this section ties your identity to the domains and IPs listed in your mTLS certificate's CN/SAN. Webhook callback URLs are not subject to this constraint. You can — and typically should — receive webhooks on a separate domain/endpoint from the one you use to call the Axys API, secured according to your own architecture (e.g. a public HTTPS endpoint behind your own WAF, authentication, and rate limiting).

3-D Secure OTP delivery

This is the most fully specified webhook pattern on the platform today, and its design — separating "who needs this" from "what is it" — is a useful model for how callback security works here generally.

Subscribing

Subscribe to OTP delivery for a card with POST /otp/listeners, optionally including a webhookUrl:

• Subscribe by cardId (recommended, current approach) — OTPs for card-not-present transactions on that specific card will be delivered.
• Subscribe by cardholderId (legacy) — OTPs for all of that cardholder's cards will be delivered. This was the original method, before card-level subscriptions existed. Subscribing card-by-card is recommended going forward, since it gives you a clean 1:1 mapping between a card and a subscription token.

🚧

3-D Secure must also be enabled on your Program. A subscription on a card in a Program that doesn't have 3-D Secure enabled will not produce OTPs. Program-level 3-D Secure configuration is part of Account Management — see Card Programs & Designs.

The subscription response includes a unique token. This token has its own expiresAt field, which is currently always null — the subscription itself does not expire (though the field exists for future use). Store this token, keyed by cardId — you'll need it both to retrieve OTPs and to unsubscribe.

The callback — and why it doesn't contain the OTP

When a card-not-present transaction triggers 3-D Secure on a subscribed card, Axys sends a callback to your webhookUrl. This callback contains only the cardId (or cardholderId, for legacy subscriptions) — never the OTP itself.

This is a deliberate security design: an OTP and the identity of the card/cardholder it belongs to are never transmitted in the same message. A single intercepted callback reveals only that some card needs an OTP delivered — not which one, and not the code.

Retrieving the OTP

On receiving a callback, look up the subscription token you stored for that cardId, then retrieve the OTP itself:

GET /v2/otp/{token}

This response includes the OTP code and its own expiresAt — unlike the subscription token, this expiry is variable and enforced. Deliver the OTP to the cardholder (SMS, push notification, in-app display, etc.) before it expires.

End-to-end flow

sequenceDiagram
    participant Cardholder
    participant Network as Card Network
    participant Axys
    participant You as Your webhook endpoint
    participant Store as Your token store

    Note over You,Axys: Setup — once per card
    You->>Axys: POST /otp/listeners (cardId, webhookUrl)
    Axys->>You: 200 — subscription token (expiresAt: null)
    You->>Store: Save token, keyed by cardId

    Note over Cardholder,Axys: At transaction time
    Cardholder->>Network: Card-not-present purchase
    Network->>Axys: 3-D Secure authentication request
    Axys->>You: Webhook — cardId only (no OTP)
    You->>Store: Look up token for this cardId
    You->>Axys: GET /otp/{token}
    Axys->>You: OTP code + expiresAt (short-lived)
    You->>Cardholder: Deliver OTP (SMS / push / etc.)
    Cardholder->>Network: Enter OTP to complete purchase

Unsubscribing

The same token is used to unsubscribe:

DELETE /v2/otp/{token}

Security notes

• Encrypt stored tokens at rest. A token grants the ability to retrieve OTPs (until used/expired) and to unsubscribe — treat it as a credential.
• Because the callback identifies the card/cardholder but not the OTP, and the OTP retrieval requires a token you already hold, neither the callback nor the retrieval alone is sufficient to compromise an OTP delivery — both your stored token and the callback are needed.

For the full picture of how this fits into a card-not-present transaction, see 3-D Secure and Subscribe to 3-DS One-Time Passcodes.

Certificate expiry reminders

As covered in mTLS Certificates & CSR and Credentials & Key Rotation, certificate expiry reminders are sent at 30, 15, and 5 days before a certificate expires.

📘

The configuration of where these reminders are delivered (email vs. webhook, and how that's set up per Tenant) is part of Account Management and is established during onboarding — confirm your preferred delivery channel with your Axys onboarding contact.

Securing your webhook endpoint

General best practices, applicable to both callback types above:

• Serve your webhook endpoint over HTTPS.
• Respond quickly (e.g. 2xx) to acknowledge receipt, and do any further processing (like the OTP retrieval call above) asynchronously if it might take longer than your endpoint's timeout.
• Validate that any cardId/cardholderId in a callback belongs to your Program before acting on it.
• Design your handler to be safe to run more than once for the same event — treat idempotent handling as the safer assumption for any webhook delivery.

Tracking other events

For event types beyond 3-D Secure OTP delivery and certificate expiry reminders — for example, transaction settlement, cardholder compliance status changes, or digital-asset deposit confirmations — poll the relevant endpoints rather than relying on a webhook:

This page will be updated as the webhook event catalog grows.

What's next

• 3-D Secure
• Subscribe to 3-DS One-Time Passcodes
• Credentials & Key Rotation