Webhooks

Cards add five webhook event types on top of Grid’s existing webhook infrastructure. Signature verification (X-Grid-Signature) and retry behavior are identical to the rest of Grid — see Authentication and Webhooks for the underlying mechanics. One covers the card itself; the others cover a card transaction’s lifecycle.

Event types

Type	Fires on
`CARD.STATE_CHANGE`	`PROCESSING → ACTIVE`, `→ CLOSED (ISSUER_REJECTED)`, and every subsequent `ACTIVE ⇄ FROZEN` and `→ CLOSED` transition.
`CARD_TRANSACTION.AUTHORIZED`	An authorization is approved and a hold is placed on the funding source.
`CARD_TRANSACTION.PARTIALLY_SETTLED`	A clearing posted, but more are still expected.
`CARD_TRANSACTION.SETTLED`	All clearings have posted. Also fires for a merchant return, which posts as its own `CREDIT` row linked via `originalTransactionId`.
`CARD_TRANSACTION.DECLINED`	The authorization was declined before any money moved.
`CARD_TRANSACTION.EXCEPTION`	The transaction settled to the network but the pull from the funding source failed.

All of them carry the standard envelope:

{
  "id": "Webhook:019542f5-b3e7-1d02-0000-000000000020",
  "type": "CARD.STATE_CHANGE",
  "timestamp": "2026-05-08T14:11:00Z",
  "data": { /* the affected Card or CardTransaction resource */ }
}

The id is unique per delivery and safe to use for idempotency.

CARD.STATE_CHANGE

The data payload is the post-change Card resource. Example — activation after issuance:

{
  "id": "Webhook:019542f5-b3e7-1d02-0000-000000000020",
  "type": "CARD.STATE_CHANGE",
  "timestamp": "2026-05-08T14:11:00Z",
  "data": {
    "id": "Card:019542f5-b3e7-1d02-0000-000000000010",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "state": "ACTIVE",
    "brand": "VISA",
    "form": "VIRTUAL",
    "last4": "4242",
    "expMonth": 12,
    "expYear": 2029,
    "fundingSources": [
      "InternalAccount:019542f5-b3e7-1d02-0000-000000000002"
    ],
    "currency": "USD",
    "processorRef": "card_b81c2a4f",
    "issuerRef": "lead_card_7a1b9c3d",
    "createdAt": "2026-05-08T14:10:00Z",
    "updatedAt": "2026-05-08T14:11:00Z"
  }
}

Common branches to handle in your consumer:

state: "ACTIVE" after PROCESSING — the card is live. To reveal the full card details, request a reveal with POST /cards/{id}/reveal right before rendering its short-lived panEmbedUrl in an iframe — webhook payloads never carry a reveal URL.
state: "CLOSED", stateReason: "ISSUER_REJECTED" — the issuer rejected provisioning; offer to issue a new card.
state: "FROZEN" / state: "ACTIVE" — reflect the freeze toggle in your UI.
state: "CLOSED", stateReason: "CLOSED_BY_PLATFORM" — close confirmed; stop showing the card.

Card-transaction lifecycle

Each CARD_TRANSACTION.* event carries the full CardTransaction resource. Not every delivery changes status: a merchant return has no event type of its own and re-fires CARD_TRANSACTION.SETTLED with the same status, so treat a repeated SETTLED as a new update and read refundedAmount to tell it apart from the original settlement. See Reconciliation for the underlying event model.

Idempotency & retries

Webhook deliveries are at-least-once. Track processed id values and return 200 on duplicates, or return 409 and let Grid stop retrying. Both shapes are accepted by Grid’s webhook infrastructure.

Overview

Onboarding

Card management

Transactions

Card design

Platform tools

Event types

CARD.STATE_CHANGE

Card-transaction lifecycle

Idempotency & retries

​Event types

​CARD.STATE_CHANGE

​Card-transaction lifecycle

​Idempotency & retries

Event types

CARD.STATE_CHANGE

Card-transaction lifecycle

Idempotency & retries