Skip to main content
Every webhook delivery is an event envelope with a type field. The data shape depends on the type. When subscribing, you can list specific types ("card.created"), prefix wildcards ("card.*"), or the catch-all ("*").

​
Cards

​
card.created

A new card was created via POST /api/v1/cards. 
{
  "type": "card.created",
  "data": {
    "id": "cm3abc123",
    "cardholder_id": "ch_abc123",
    "last4": "4242",
    "expiry": "03/28",
    "spend_limit_cents": 1000,
    "balance_cents": 1000,
    "status": "OPEN",
    "created_at": "2026-05-17T12:00:00.000Z"
  }
}

​
card.updated

A card’s balance or status changed (for example, a transaction settled and reduced the balance, or the card transitioned to IN_USE). 
{
  "type": "card.updated",
  "data": {
    "id": "cm3abc123",
    "last4": "4242",
    "status": "IN_USE",
    "balance_cents": 850,
    "spend_limit_cents": 1000
  }
}

​
card.closed

A card was closed — either by an explicit DELETE /api/v1/cards/:id call, or automatically after the balance reached zero. 
{
  "type": "card.closed",
  "data": {
    "id": "cm3abc123",
    "cardholder_id": "ch_abc123",
    "last4": "4242",
    "status": "CLOSED",
    "reason": "manual"
  }
}
reason is one of manual (closed via API/CLI) or balance_exhausted (auto-closed when the balance hit zero).

​
Cardholders

​
cardholder.created

A new cardholder was created via POST /api/v1/cardholders. 
{
  "type": "cardholder.created",
  "data": {
    "id": "ch_abc123",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.com",
    "date_of_birth": "1815-12-10",
    "phone_number": "+14155551234",
    "created_at": "2026-05-17T12:00:00.000Z"
  }
}

​
cardholder.updated

A cardholder was updated via PATCH /api/v1/cardholders/:id. The updated_fields array lists which fields were changed in that request. 
{
  "type": "cardholder.updated",
  "data": {
    "id": "ch_abc123",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada.new@example.com",
    "date_of_birth": "1815-12-10",
    "phone_number": "+14155551234",
    "updated_fields": ["email"],
    "updated_at": "2026-05-17T13:30:00.000Z"
  }
}

​
cardholder_onboarding_session.completed

A hosted onboarding session finished: the end user verified their email and consented, and a cardholder in your organization is now linked to their AgentCard account. claimed_existing_cardholder is true when an existing cardholder was claimed (in that case no separate cardholder.created event fires). 
{
  "type": "cardholder_onboarding_session.completed",
  "data": {
    "id": "cos_a1b2c3d4e5f6a7b8c9d0e1f2",
    "status": "completed",
    "cardholder_id": "ch_abc123",
    "external_user_id": "user_123",
    "email": "ada@example.com",
    "claimed_existing_cardholder": false,
    "state": "f3a9c2",
    "completed_at": "2026-06-10T18:04:12.000Z"
  }
}

​
Transactions

Transaction events all share the same payload shape. The status and type together tell you exactly where the transaction is in its lifecycle.

​
transaction.authorized

A merchant authorization succeeded. Funds are held against the card; balance is reduced. 
{
  "type": "transaction.authorized",
  "data": {
    "id": "txn_8f3e2d1c",
    "card_id": "cm3abc123",
    "last4": "4242",
    "amount_cents": 1500,
    "merchant": "STRIPE.COM",
    "mcc": "5734",
    "status": "PENDING",
    "balance_cents": 8500
  }
}

​
transaction.declined

The authorization was declined by the network or the issuer. No funds were held. The decline_reason field carries the reason code. 
{
  "type": "transaction.declined",
  "data": {
    "id": "txn_8f3e2d1c",
    "card_id": "cm3abc123",
    "last4": "4242",
    "amount_cents": 9999,
    "merchant": "EXAMPLE STORE",
    "mcc": "5999",
    "status": "DECLINED",
    "balance_cents": 1000,
    "decline_reason": "INSUFFICIENT_FUNDS"
  }
}

​
transaction.cleared

A prior authorization has settled. The amount may differ slightly from the authorization (e.g. tips). 
{
  "type": "transaction.cleared",
  "data": {
    "id": "txn_8f3e2d1c",
    "card_id": "cm3abc123",
    "last4": "4242",
    "amount_cents": 1500,
    "merchant": "STRIPE.COM",
    "status": "SETTLED",
    "balance_cents": 8500
  }
}

​
transaction.voided

An authorization was voided before settlement. The held amount is released back to the card balance. 
{
  "type": "transaction.voided",
  "data": {
    "id": "txn_8f3e2d1c",
    "card_id": "cm3abc123",
    "last4": "4242",
    "amount_cents": 1500,
    "merchant": "STRIPE.COM",
    "status": "VOIDED",
    "balance_cents": 10000
  }
}

​
Balance

​
balance.low

The card’s remaining balance dropped to $10 or less but is still positive. Useful for top-up or warning workflows. Fires at most once per transaction; the card may still be used until balance hits zero. 
{
  "type": "balance.low",
  "data": {
    "card_id": "cm3abc123",
    "last4": "4242",
    "balance_cents": 850
  }
}

​
Subscription wildcards

Each event has a noun-scoped prefix. Use these in your enabled_events list to subscribe to families:
PatternMatches
card.*card.created, card.updated, card.closed
cardholder.*cardholder.created, cardholder.updated
cardholder_onboarding_session.*cardholder_onboarding_session.completed
transaction.*transaction.authorized, .declined, .cleared, .voided
balance.*balance.low
*All event types