Skip to content

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 namenotificationStateMeaning
card_application.status_changedn/aApplication status changed
card_application.completion_link_changedn/aIssuer issued a new completion link (opt-in)
card_user.kyc_status_changedn/aAgio KYC status for a cardholder changed (opt-in)
card_transaction.authorizedcreated_notifiedSpend authorized; amount is pending and held
card_transaction.settledcompleted_notifiedTransaction completed
card_transaction.declineddeclined_notifiedSpend declined
card_transaction.reversedreversed_notifiedTransaction reversed
card_transaction.createdanyA transaction row of any type was first recorded
card_transaction.updatedanyA tracked field of a transaction row changed
card_wallet.provisionedanyCard added to Apple Pay or Google Pay
card_wallet.provisioning_declinedanyWallet add declined
card_wallet.token_changedanyWallet token suspended, resumed or deleted

Subscribe using GraphQL enum values; received events use dotted wire names:

GraphQL enumReceived eventName
CARD_APPLICATION_STATUS_CHANGEDcard_application.status_changed
CARD_APPLICATION_COMPLETION_LINK_CHANGEDcard_application.completion_link_changed
CARD_USER_KYC_STATUS_CHANGEDcard_user.kyc_status_changed
CARD_TRANSACTION_AUTHORIZEDcard_transaction.authorized
CARD_TRANSACTION_SETTLEDcard_transaction.settled
CARD_TRANSACTION_DECLINEDcard_transaction.declined
CARD_TRANSACTION_REVERSEDcard_transaction.reversed
CARD_TRANSACTION_CREATEDcard_transaction.created
CARD_TRANSACTION_UPDATEDcard_transaction.updated
CARD_WALLET_PROVISIONEDcard_wallet.provisioned
CARD_WALLET_PROVISIONING_DECLINEDcard_wallet.provisioning_declined
CARD_WALLET_TOKEN_CHANGEDcard_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:

HeaderValue
x-agio-eventDotted event name
x-agio-delivery-idAttempt identifier; changes on retry
x-agio-timestampUnix time in milliseconds
x-agio-signatureHex 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.

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"
  }
}
nextStepstatusMeaning
APPLYAPPROVEDCompleted GREEN review at or above the required level. Submit the card application.
RESUBMITACTION_REQUIREDRejected with retry allowed. Have the cardholder correct and resubmit.
TERMINALREJECTEDRejected with no retry.
AWAIT_REVIEWPENDING_REVIEWSubmitted 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.

GroupFields
Record and ownershipcardTransactionId, cardTransactionExternalId, cardApplicationId, cardUserId, cardCompanyId
LifecycleeventType, transactionType, status, notificationState, createdAt, updatedAt
CardcardId, cardExternalId, cardType
Amountsamount, currency, localAmount, localCurrency, authorizedAmount, authorizationUpdateAmount
AuthorizationauthorizationMethod, authorizedAt, declinedReason
MerchantmerchantName, merchantCity, merchantCountry, merchantCategory, merchantCategoryCode, enrichedMerchantName, enrichedMerchantIcon, enrichedMerchantCategory
Collateral transferchainId, walletAddress, transactionHash
Other transfer detailstransferId, 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.codeDecided byWhat the cardholder can do
TOKENIZATION_LIMIT_EXCEEDEDCard issuerRetry after the limit window. description names the limit reached.
UNSUPPORTED_REGIONCard issuerNone. Apple Pay is not available in the country of residence.
UNKNOWN_USER_COUNTRYCard issuerSet the cardholder's country of residence, then retry.
CVC_NOT_VALIDCard issuerRe-enter the correct CVC.
EXPIRY_DATE_INVALIDCard issuerRe-enter the correct expiry date.
WALLET_PROVIDER_RISK_THRESHOLD_EXCEEDEDWallet providerWait 24 to 48 hours. After a push decline, a manual add may work.
DEVICE_SCORE_TOO_LOWWallet providerTry a different device or update the OS.
EXCESSIVE_PROVISIONING_ATTEMPTS_ACROSS_ACCOUNTSWallet providerWait 24 to 48 hours.
EXCESSIVE_CARDS_AND_PROVISIONING_ATTEMPTSWallet providerWait 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.

EventFires when
card_transaction.createdA transaction row is first recorded
card_transaction.updatedstatus, 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:

FieldMeaning
previousStatusstatus before the change. Null on created.
previousAmountamount before the change. Null on created.

Coverage ​

transactionTypecreated and updatedLifecycle events
spendYesauthorized, settled, declined, reversed
collateralYesSame as spend, per notificationState
paymentYesNone
feeYesNone

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, so created and updated can share one handler.
  • Apply an update only when its updatedAt is newer than the stored one. Events can arrive out of order, and an older updated must 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.

Next: Handle errors and uncertain outcomes.