LIlightsparkdev
Webhooks

Card PIN status change

Sent when Grid records a change to a card's PIN status, including changes detected after a hosted PIN submission, an API request, or a PIN becoming blocked. The data contains the updated Card resource and its new pinStatus.

Initial card creation does not trigger this event. Changing an existing PIN while its status remains OK does not trigger it either; use the submission result to confirm that the PIN changed.

Changes made outside the Grid API are detected asynchronously. The event describes the status Grid observed, not every intermediate PIN status. Delivery can be repeated or arrive out of order. Deduplicate by id and use data.updatedAt to avoid replacing newer card data with an older snapshot. Read pinStatus from GET /cards/{id} to retrieve the card's saved status.

Verify the X-Grid-Signature header using your Grid webhook public key, as for other Grid webhooks. No PIN, encrypted PIN block, or PIN-entry session credential is included.

postWebhookcard-pin-status-change

Payload

idstring required

Unique identifier for this webhook delivery (can be used for idempotency)

type'CARD.PIN_STATUS_CHANGE' required

Type of webhook event in OBJECT.EVENT dot-notation. The part before the dot identifies the resource, the part after identifies the event. This lets consumers route purely on type without inspecting data.status. CARD_AUTHORIZATION.REQUEST is a synchronous decision request that Grid sends only while cardConfigs.realTimeAuthorization is set.

timestampstring date-time required

ISO 8601 timestamp of when the webhook was sent

Example payload

{
  "id": "Webhook:019542f5-b3e7-1d02-0000-000000000007",
  "timestamp": "2025-08-15T14:32:00Z",
  "data": {
    "id": "Card:019542f5-b3e7-1d02-0000-000000000010",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "platformCardId": "card-emp-001",
    "pinStatus": "OK",
    "pinUnblockAvailableAt": "2026-10-15T15:00:00Z",
    "last4": "4242",
    "expMonth": 12,
    "expYear": 2029,
    "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
    "cardCapabilities": {
      "supportsVelocityLimits": true,
      "supportsPanReveal": true,
      "supportsDigitalWalletTokenization": true
    },
    "maxNetworkRiskScore": 700,
    "allowedMccs": [
      "5411"
    ],
    "blockedMccs": [
      "7995"
    ],
    "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
    "currency": "USD",
    "processorRef": "card_b81c2a4f",
    "issuerRef": "lead_card_7a1b9c3d",
    "createdAt": "2026-05-08T14:10:00Z",
    "updatedAt": "2026-05-08T14:11:00Z"
  }
}

Response

Webhook received successfully

Changes

Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.