Webhooks
Card state change
Webhook that is called when a card's lifecycle state changes. Fires on PENDING_ISSUE → ACTIVE, on PENDING_ISSUE → CLOSED (ISSUER_REJECTED) when issuer provisioning fails, and on every subsequent ACTIVE ⇄ FROZEN and → CLOSED transition.
This endpoint should be implemented by clients of the Grid API.
Authentication
The webhook includes a signature in the X-Grid-Signature header that allows you to verify that the webhook was sent by Grid. To verify the signature:
- Get the Grid public key provided to you during integration
- Decode the base64 signature from the header
- Create a SHA-256 hash of the request body
- Verify the signature using the public key and the hash
If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.
postWebhookcard-state-change
Payload
Example payload
{
"id": "Webhook:019542f5-b3e7-1d02-0000-000000000007",
"timestamp": "2025-08-15T14:32:00Z",
"data": {
"id": "Card:019542f5-b3e7-1d02-0000-000000000010",
"cardholderId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
"platformCardId": "card-emp-aary-001",
"last4": "4242",
"expMonth": 12,
"expYear": 2029,
"panEmbedUrl": "https://embed.lithic.com/iframe/...?t=...",
"fundingSources": [
"InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
"InternalAccount:019542f5-b3e7-1d02-0000-000000000003"
],
"currency": "USD",
"issuerRef": "lithic_card_4f8d3a2b1c",
"createdAt": "2026-05-08T14:10:00Z",
"updatedAt": "2026-05-08T14:11:00Z"
}
}Response
Webhook received successfully