Appearance
Receive webhooks
Subscribe a public HTTPS receiver to application status changes and card transactions. A subscription covers your partner organization's managed cardholders; you do not need one subscription per customer or cardholder.
Webhook deliveries use a per-subscription signing secret. This is separate from the client_secret used to sign your API requests.
Subscribe
graphql
mutation Subscribe($input: SubscribePartnerWebhookInput!) {
subscribePartnerWebhook(input: $input) {
success
subscriptionId
signingSecret
errorCode
errorMessage
}
}json
{
"input": {
"url": "https://partner.example/agio-webhooks",
"events": ["CARD_APPLICATION_STATUS_CHANGED", "CARD_TRANSACTION_AUTHORIZED", "CARD_TRANSACTION_SETTLED", "CARD_TRANSACTION_DECLINED", "CARD_TRANSACTION_REVERSED"]
}
}Store subscriptionId and signingSecret after success: true. The secret is returned once and cannot be read back. A single subscription can include every event you need.
Only one active subscription is allowed for the same partner and canonical URL. Agio normalizes the scheme and host, removes fragments and trailing path slashes, and preserves path and query case. A duplicate returns DUPLICATE_ACTIVE_SUBSCRIPTION. To replace its event set, unsubscribe and create a new subscription.
Subscribed events
| Event name | notificationState | Meaning |
|---|---|---|
card_application.status_changed | n/a | Application status changed |
card_application.completion_link_changed | n/a | Issuer issued a new completion link (opt-in) |
card_user.kyc_status_changed | n/a | Agio KYC status for a cardholder changed (opt-in) |
card_transaction.authorized | created_notified | Spend authorized; amount is pending and held |
card_transaction.settled | completed_notified | Transaction completed |
card_transaction.declined | declined_notified | Spend declined |
card_transaction.reversed | reversed_notified | Transaction reversed |
card_transaction.created | any | A transaction row of any type was first recorded |
card_transaction.updated | any | A tracked field of a transaction row changed |
card_wallet.provisioned | any | Card added to Apple Pay or Google Pay |
card_wallet.provisioning_declined | any | Wallet add declined |
card_wallet.token_changed | any | Wallet token suspended, resumed or deleted |
Subscribe using GraphQL enum values; received events use dotted wire names:
| GraphQL enum | Received eventName |
|---|---|
CARD_APPLICATION_STATUS_CHANGED | card_application.status_changed |
CARD_APPLICATION_COMPLETION_LINK_CHANGED | card_application.completion_link_changed |
CARD_USER_KYC_STATUS_CHANGED | card_user.kyc_status_changed |
CARD_TRANSACTION_AUTHORIZED | card_transaction.authorized |
CARD_TRANSACTION_SETTLED | card_transaction.settled |
CARD_TRANSACTION_DECLINED | card_transaction.declined |
CARD_TRANSACTION_REVERSED | card_transaction.reversed |
CARD_TRANSACTION_CREATED | card_transaction.created |
CARD_TRANSACTION_UPDATED | card_transaction.updated |
CARD_WALLET_PROVISIONED | card_wallet.provisioned |
CARD_WALLET_PROVISIONING_DECLINED | card_wallet.provisioning_declined |
CARD_WALLET_TOKEN_CHANGED | card_wallet.token_changed |
A dotted name in the subscription's events input fails GraphQL validation. subscription.created is a test event emitted by the server and cannot be explicitly subscribed to.
Verify each delivery
Deliveries are JSON POSTs with these headers:
| Header | Value |
|---|---|
x-agio-event | Dotted event name |
x-agio-delivery-id | Attempt identifier; changes on retry |
x-agio-timestamp | Unix time in milliseconds |
x-agio-signature | Hex HMAC-SHA256 of ${timestamp}.${rawBody} using your webhook signing secret |
Preserve the raw request bytes before your framework's JSON parser changes them. Verify the signature in constant time, then parse and persist the event. This verifier accepts an array of secrets so it can handle a rotation overlap:
typescript
import { createHmac, timingSafeEqual } from "node:crypto";
function verifyWebhook(rawBody: Uint8Array, timestamp: string | undefined, signature: string | undefined, signingSecrets: string[]) {
if (!timestamp || !/^\d+$/.test(timestamp) || !signature || !/^[a-fA-F0-9]{64}$/.test(signature)) return false;
const time = Number(timestamp);
if (!Number.isFinite(time) || Math.abs(Date.now() - time) > 5 * 60_000) return false;
const received = Buffer.from(signature, "hex");
return signingSecrets.some((secret) => {
const expected = createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest();
return timingSafeEqual(received, expected);
});
}Return a 2xx response after signature verification and durable event acceptance, then do business processing asynchronously. Each attempt times out after 30 seconds. Redirects are treated as failures.
Your receiver must be publicly routable over HTTPS. Localhost, private or loopback IPs, cloud metadata hosts, and hostnames resolving to private IPs are rejected before delivery. Use a deployed endpoint or a public HTTPS tunnel for development. The starter kit includes an Express receiver.
Application events
json
{
"eventName": "card_application.status_changed",
"eventId": "cas_<stable event hash>",
"deliveredAt": "2026-10-04T06:00:00.123Z",
"data": {
"cardApplicationId": 42,
"cardApplicationExternalId": "<issuer application UUID>",
"cardUserId": "<cardUserId>",
"oldStatus": "PENDING",
"newStatus": "APPROVED",
"nextStep": null,
"reasonDescription": null,
"completionUrl": null
}
}Use cardApplicationId to join the event to your stored application. nextStep is RESUBMIT, AWAIT_REVIEW, TERMINAL, or null. It is null for APPROVED and ACTIVE.
completionUrl is a composed signed verification link when the application is NEEDSINFORMATION, NEEDSVERIFICATION, NOTSTARTED, or TOSNOTACCEPTED. Open it as returned. It is null for every other status, including approval, denial, and manual review. When available, the event also carries continueUrl next to completionUrl, a stable link you can store and send to the cardholder: it stays valid for 14 days and opens a fresh verification page each time. reasonDescription may be null, including when a moderation comment has not reached the record at delivery time. Act on the status and nextStep; use application queries to reconcile current state.
Completion link changed
Opt-in: only subscribers of CARD_APPLICATION_COMPLETION_LINK_CHANGED receive it. It fires when the issuer issues a new completion link while the application status stays the same, in a status that carries a completionUrl. A status change still arrives as card_application.status_changed with the current link, never as both.
json
{
"eventName": "card_application.completion_link_changed",
"eventId": "cal_<stable event hash>",
"deliveredAt": "2026-10-04T06:00:00.123Z",
"data": {
"cardApplicationId": 42,
"cardUserId": "<cardUserId>",
"applicationStatus": "NEEDSVERIFICATION",
"completionUrl": "https://<composed signed verification link>"
}
}Send the cardholder to the latest completionUrl. Open it as returned. It lasts 24 hours: fetch a fresh one when the cardholder opens it.
Cardholder KYC status changed
Opt-in: only subscribers of CARD_USER_KYC_STATUS_CHANGED receive it. It fires when the Agio KYC review for a cardholder you created changes state. It signals Agio's KYC result only: the issuer still makes its own decision on the card application. Agio sends no email or SMS to the cardholder, and the payload carries no link; call createPartnerCardUserKycSession when the cardholder needs one.
json
{
"eventName": "card_user.kyc_status_changed",
"eventId": "cku_<stable event hash>",
"deliveredAt": "2026-10-04T06:00:00.123Z",
"data": {
"cardUserId": "<cardUserId>",
"applicationCardUserId": "<cardUserId from card_application.status_changed>",
"status": "APPROVED",
"nextStep": "APPLY",
"reasonDescription": null,
"occurredAt": "2026-10-04T05:59:58.000Z"
}
}nextStep | status | Meaning |
|---|---|---|
APPLY | APPROVED | Completed GREEN review at or above the required level. Submit the card application. |
RESUBMIT | ACTION_REQUIRED | Rejected with retry allowed. Have the cardholder correct and resubmit. |
TERMINAL | REJECTED | Rejected with no retry. |
AWAIT_REVIEW | PENDING_REVIEW | Submitted or on hold. Wait for the next event. |
status is the cardholder's current state, computed the same way as partnerCardUserKycStatus. NOT_STARTED and IN_PROGRESS send no event, so a reset or an unfinished submission is silent until the cardholder submits again; call partnerCardUserKycStatus to read it.
reasonDescription is the reviewer's moderation comment when present, otherwise null. While the status is PENDING_REVIEW it is the fixed text "The application is under review. No action is needed." It matches reason in partnerCardUserKycStatus. Applicants are matched to a cardholder only by the linked applicant id, never by name or date of birth.
cardUserId is the id createPartnerCardUser returned. After a card application exists, the event also carries applicationCardUserId: the cardUserId that card_application.status_changed sends for the newest application of the same cardholder. The field is absent before the application exists. partnerCardUserKycStatus accepts either id.
Transaction events
All transaction events use the same envelope. This is an abbreviated settled-spend example:
json
{
"eventName": "card_transaction.settled",
"eventId": "ctx_<stable event hash>",
"deliveredAt": "2026-10-04T06:00:00.123Z",
"data": {
"cardTransactionId": 5396,
"cardTransactionExternalId": "<issuer transaction UUID>",
"cardId": 86,
"cardExternalId": "<issuer card UUID>",
"cardApplicationId": 42,
"cardUserId": "<cardUserId>",
"cardCompanyId": "<issuer company UUID>",
"eventType": "transaction.completed",
"transactionType": "spend",
"status": "completed",
"notificationState": "completed_notified",
"amount": 9500,
"currency": "USD",
"localAmount": 8700,
"localCurrency": "EUR",
"merchantName": "Example Merchant",
"postedAt": "2026-10-04T05:59:00.000Z",
"updatedAt": "2026-10-04T05:59:01.000Z"
}
}Spend amounts are integer minor units: amount: 9500 with currency: "USD" means $95. localAmount and localCurrency describe the original merchant currency. A transaction keeps its cardTransactionExternalId through authorization, settlement, and reversal. Events can arrive out of order; reconcile against current transaction state rather than assuming delivery order is the lifecycle order.
Authorized spend has status: "pending" and already reduces available spending power. Show pending transactions alongside settled purchases. A declined attempt does not hold funds. A reversal can follow settlement.
Field availability
The payload includes the following fields when source data is available. Handle null values, including for identifiers or timestamps that have not propagated.
| Group | Fields |
|---|---|
| Record and ownership | cardTransactionId, cardTransactionExternalId, cardApplicationId, cardUserId, cardCompanyId |
| Lifecycle | eventType, transactionType, status, notificationState, createdAt, updatedAt |
| Card | cardId, cardExternalId, cardType |
| Amounts | amount, currency, localAmount, localCurrency, authorizedAmount, authorizationUpdateAmount |
| Authorization | authorizationMethod, authorizedAt, declinedReason |
| Merchant | merchantName, merchantCity, merchantCountry, merchantCategory, merchantCategoryCode, enrichedMerchantName, enrichedMerchantIcon, enrichedMerchantCategory |
| Collateral transfer | chainId, walletAddress, transactionHash |
| Other transfer details | transferId, transferSourceRail, transferDestinationRail, feeDescription, postedAt |
authorizationMethod is the POS entry-mode code, not a card-network approval code. eventType is the ingested issuer or Agio event category; it is different from the partner webhook's eventName.
Wallet events
Wallet events report Apple Pay and Google Pay decisions. This is a declined add:
json
{
"eventName": "card_wallet.provisioning_declined",
"eventId": "cwe_<stable event hash>",
"deliveredAt": "2026-11-06T14:04:51.123Z",
"data": {
"cardId": 2204,
"cardExternalId": "0157e2aa-bc47-4ecb-8888-5179447405ab",
"last4": "7210",
"tokenWallet": "Apple",
"reasonCode": "PROVISIONING_DECLINED",
"decisionReason": {
"code": "WALLET_PROVIDER_RISK_THRESHOLD_EXCEEDED",
"description": "This tokenization request was declined by the wallet provider."
},
"decidedBy": "wallet_provider",
"occurredAt": "2026-11-06T14:04:50.322Z"
}
}card_wallet.provisioned has the same shape, with reasonCode, decisionReason and decidedBy set to null. card_wallet.token_changed carries TOKEN_SUSPENDED, TOKEN_RESUMED or TOKEN_DELETED in reasonCode, for programs with network token reporting enabled. Any other wallet notification from the issuer also arrives as this event, so treat reasonCode as an open string. decidedBy is card_issuer, wallet_provider or unknown.
The wallet shows the cardholder the same "Could Not Add Card" error for every decline. Match decisionReason.code to the support report:
decisionReason.code | Decided by | What the cardholder can do |
|---|---|---|
TOKENIZATION_LIMIT_EXCEEDED | Card issuer | Retry after the limit window. description names the limit reached. |
UNSUPPORTED_REGION | Card issuer | None. Apple Pay is not available in the country of residence. |
UNKNOWN_USER_COUNTRY | Card issuer | Set the cardholder's country of residence, then retry. |
CVC_NOT_VALID | Card issuer | Re-enter the correct CVC. |
EXPIRY_DATE_INVALID | Card issuer | Re-enter the correct expiry date. |
WALLET_PROVIDER_RISK_THRESHOLD_EXCEEDED | Wallet provider | Wait 24 to 48 hours. After a push decline, a manual add may work. |
DEVICE_SCORE_TOO_LOW | Wallet provider | Try a different device or update the OS. |
EXCESSIVE_PROVISIONING_ATTEMPTS_ACROSS_ACCOUNTS | Wallet provider | Wait 24 to 48 hours. |
EXCESSIVE_CARDS_AND_PROVISIONING_ATTEMPTS | Wallet provider | Wait 24 to 48 hours. |
New codes can appear without notice, so treat code as an open string.
Limits of this data:
- No event fires when the cardholder leaves before a decision, or when the wallet blocks the add itself. A quiet feed does not prove that adds work.
- No field says whether the cardholder added the card by hand or through push provisioning.
Read the same history from AgioCard_card_wallet_event, and the wallets reported as added from token_wallets on AgioCard_card. Without network token reporting, a wallet that the cardholder removes stays in this list.
Collateral events
transactionType: "collateral" describes funds entering or leaving the cardholder's shared collateral balance. Its signed amount indicates direction: positive for deposits, negative for withdrawals. walletAddress, chainId, and transactionHash describe the on-chain movement when available.
Collateral is shared across the cardholder's cards, so cardId and cardExternalId are null by design. Merchant and authorization fields are also inapplicable. Reconcile collateral by cardUserId and the application or company identity, rather than by an individual card.
For spend, postedAt generally appears after settlement; for collateral, it records posting. Do not apply a universal "null until a spend settles" rule to every transaction type.
Generic transaction events
card_transaction.created and card_transaction.updated cover every transaction type that belongs to a card application, including payment and fee rows that the four lifecycle events above never emit. Subscribe with CARD_TRANSACTION_CREATED and CARD_TRANSACTION_UPDATED; they are opt-in like every other event.
| Event | Fires when |
|---|---|
card_transaction.created | A transaction row is first recorded |
card_transaction.updated | status, amount, authorizedAmount, authorizationUpdateAmount, declinedReason or postedAt changes |
An update that changes none of those fields sends nothing. The data block is the same as the other transaction events, plus two fields:
| Field | Meaning |
|---|---|
previousStatus | status before the change. Null on created. |
previousAmount | amount before the change. Null on created. |
Coverage
transactionType | created and updated | Lifecycle events |
|---|---|---|
spend | Yes | authorized, settled, declined, reversed |
collateral | Yes | Same as spend, per notificationState |
payment | Yes | None |
fee | Yes | None |
A partner subscribed to both card_transaction.settled and card_transaction.updated receives both for one settlement. They carry the same cardTransactionExternalId and different eventId values, so treat them as two notifications about one transaction.
For a fee row, cardTransactionExternalId is the issuer's charge id for that fee.
Ownership
A transaction is delivered to the partner that owns its card application, so only rows that carry a cardApplicationId produce events. A fee row is delivered only when it carries a cardApplicationId. Collateral rows recorded against a company only (cardCompanyId set, no card application) are not emitted.
Receiver rules
- Deduplicate by
eventId. It is stable across retries and manual resends, and unique per change. - Upsert by
cardTransactionId, socreatedandupdatedcan share one handler. - Apply an update only when its
updatedAtis newer than the stored one. Events can arrive out of order, and an olderupdatedmust not overwrite newer state.
Test delivery and retries
After subscription creation, Agio asynchronously queues a signed subscription.created event with a test_ event ID and data: { test: true, message: "..." }. Treat it as a reachability and signature check. If it is missing, inspect the subscription and delivery history as well as endpoint reachability.
Deduplicate by the body eventId, which remains stable across retries and manual resends. Do not deduplicate by x-agio-delivery-id or deliveredAt: both identify an attempt and can change. Application event IDs begin with cas_; transaction IDs begin with ctx_.
Status events for one application can arrive seconds apart and are not guaranteed to arrive in order. On each card_application.status_changed event, read the application's current status with application queries rather than storing newStatus as it arrives.
Non-2xx responses, network failures, and timeouts are retried after 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours, 12 hours, and 24 hours, for up to eight attempts. The final failure is dead-lettered. Unsafe receiver URLs can be rejected without an HTTP attempt.
A successful delivery resets the subscription's consecutive-failure count. At 30 consecutive failures the subscription becomes inactive and queued retry jobs are drained. Monitor is_active and failure fields; an active-only query hides this failure. Fix the receiver and create a new subscription to resume delivery.
Monitor and resend deliveries
graphql
query Subscriptions {
AgioPlatform_partner_webhook_subscription(order_by: { created_at: desc }) {
id
url
events
is_active
consecutive_failures
last_delivery_at
last_failure_at
last_failure_reason
}
}Signing secrets are not exposed in read queries. Delivery history is scoped to your subscriptions:
graphql
query DeliveryHistory($subscriptionId: uuid!) {
AgioPlatform_partner_webhook_delivery(where: { subscription_id: { _eq: $subscriptionId } }, order_by: { created_at: desc }, limit: 20) {
id
event_name
event_id
http_status
attempt_number
delivered_at
failed_at
dead_lettered
}
}json
{ "subscriptionId": "<subscription UUID>" }To resend a past delivery, use its history-row id:
graphql
mutation Resend($deliveryId: ID!) {
resendPartnerWebhookDelivery(deliveryId: $deliveryId) {
success
newDeliveryId
errorCode
errorMessage
}
}json
{ "deliveryId": "<delivery history id>" }The original eventId and payload are reused. newDeliveryId identifies the queued attempt, not a delivery-history row. An inactive original subscription returns SUBSCRIPTION_INACTIVE; creating another subscription does not reactivate that old subscription or move its deliveries to the new one.
Rotate the signing secret
graphql
mutation Rotate($subscriptionId: ID!) {
rotatePartnerWebhookSecret(subscriptionId: $subscriptionId) {
success
signingSecret
previousSecretValidUntil
errorCode
errorMessage
}
}json
{ "subscriptionId": "<subscription UUID>" }Store the new secret immediately. Agio signs new deliveries with it from the cutover. Keep accepting the previous secret until previousSecretValidUntil (24 hours) for in-flight requests, then remove it from your verifier. ROTATION_RACE means another rotation won; inspect the subscription and coordinate which secret your receiver should use before retrying.
Unsubscribe
graphql
mutation Unsubscribe($subscriptionId: ID!) {
unsubscribePartnerWebhook(subscriptionId: $subscriptionId) {
success
errorCode
errorMessage
}
}json
{ "subscriptionId": "<subscription UUID>" }unsubscribePartnerWebhook sets is_active to false. The subscription stays queryable with is_active: false. Queued and delayed deliveries are drained; an already-running request can still finish. NOT_FOUND also covers a subscription outside your organization.