feat(webhooks): add CARD_TRANSACTION webhook contract

[AaryamanBhute]

Add a dedicated card-transaction webhook that fires on every state
transition of a CardTransaction (AUTHORIZED, PARTIALLY_SETTLED, SETTLED,
REFUNDED, EXCEPTION), carrying the full CardTransaction resource.

• New webhooks/card-transaction.yaml operation (cardTransactionWebhook)
• New CardTransactionWebhook schema extending BaseWebhook
• Add CARD_TRANSACTION.* values to WebhookType enum
• Register webhook in root spec and rebundle

Ports lightsparkdev/webdev#30355 into the OpenAPI source of truth.

Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ignored	Preview	Jul 15, 2026 6:03pm
grid-wallet-demo	Ignored	Preview	Jul 15, 2026 6:03pm

[AaryamanBhute]

• feat(webhooks): add CARD_TRANSACTION webhook contract #690 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

✱ Stainless preview builds for grid

This PR will update the grid SDKs with the following commit messages.

cli

chore(internal): regenerate SDK with no functional changes

go

feat(api): add card_transaction webhook events

kotlin

feat(api): add CardTransactionWebhookEvent with 5 event types to webhooks

openapi

feat(api): add card-transaction webhook endpoint and event types

php

feat(api): add CardTransactionWebhookEvent to webhooks

python

feat(api): add CardTransactionWebhookEvent webhook event type

ruby

feat(api): add CardTransactionWebhookEvent model and card transaction enum values to webhooks

typescript

feat(api): add CardTransactionWebhookEvent type to webhooks

⚠️ grid-openapi studio · code

Your SDK build had at least one "warning" diagnostic.
generate ⚠️

✅ grid-ruby studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ✅ → lint ✅ → test ✅

⚠️ grid-go studio · code

Your SDK build had a failure in the lint CI job, which is a regression from the base state.
generate ✅ → build ✅ → lint ❗ → test ❗

go get github.com/stainless-sdks/grid-go@29a91b3ea6568f0053506679d6007b74c08a82f7

⚠️ grid-kotlin studio · code

Your SDK build had a failure in the test CI job, which is a regression from the base state.
generate ⚠️ → build ✅ → lint ✅ → test ❗

⚠️ grid-python studio · code

Your SDK build had a failure in the lint CI job, which is a regression from the base state.
generate ✅ → build ✅ → lint ❗ → test ❗

pip install https://pkg.stainless.com/s/grid-python/b5373c832415bd1ce0dbd13299c731874ee920ec/grid-0.0.1-py3-none-any.whl

✅ grid-typescript studio · conflict

Your SDK build had at least one note diagnostic.

✅ grid-php studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → lint ✅ → test ✅

⚠️ grid-cli studio · code

Your SDK build had a failure in the test CI job, which is a regression from the base state.
generate ⚠️ → build ⏭️ → lint ⏭️ → test ❗

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-07-15 18:15:37 UTC

[greptile-apps]

Greptile Summary

This PR adds a card-transaction webhook to the Grid API OpenAPI spec, firing on every CardTransaction state transition (AUTHORIZED, PARTIALLY_SETTLED, SETTLED, REFUNDED, EXCEPTION) with the full resource payload. It ports the contract from webdev#30355 into the OpenAPI source of truth.

• New openapi/webhooks/card-transaction.yaml operation and openapi/components/schemas/webhooks/CardTransactionWebhook.yaml schema, following the exact same allOf BaseWebhook pattern as CardStateChangeWebhook.
• Five new CARD_TRANSACTION.* values added to WebhookType.yaml; four rich examples (authorized, settled, refunded, exception) provided in the webhook definition; both bundled specs (openapi.yaml, mintlify/openapi.yaml) updated consistently.

Confidence Score: 5/5

Safe to merge — this is a purely additive OpenAPI contract change with no runtime logic, following established patterns exactly.

The new webhook schema, operation, and enum values are fully consistent with existing analogues (CardStateChangeWebhook, card-state-change.yaml). The examples cover the key lifecycle transitions with all required CardTransaction fields present. Both bundled specs are updated in sync with the source. No logic, breaking changes, or schema conflicts introduced.

No files require special attention.

Important Files Changed

Filename	Overview
openapi/webhooks/card-transaction.yaml	New webhook operation with four detailed lifecycle examples (authorized, settled, refunded, exception); structure and response codes match other webhooks in the repo.
openapi/components/schemas/webhooks/CardTransactionWebhook.yaml	New schema using allOf + BaseWebhook pattern, narrowing type enum to CARD_TRANSACTION.* values and adding required data field; mirrors CardStateChangeWebhook exactly.
openapi/components/schemas/webhooks/WebhookType.yaml	Five new CARD_TRANSACTION.* enum values appended in the correct position before TEST; no issues.
openapi/openapi.yaml	Two-line addition registering the new card-transaction webhook $ref; correct and consistent with other webhook registrations.
openapi.yaml	Bundled spec updated identically to mintlify/openapi.yaml; content mirrors source files.
mintlify/openapi.yaml	Bundled spec updated identically to openapi.yaml; content mirrors source files.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Card Issuer
    participant Grid API
    participant Client Webhook

    Card Issuer->>Grid API: Authorization approved
    Grid API->>Client Webhook: CARD_TRANSACTION.AUTHORIZED (CardTransaction)

    Card Issuer->>Grid API: Partial clearing posted
    Grid API->>Client Webhook: CARD_TRANSACTION.PARTIALLY_SETTLED (CardTransaction)

    Card Issuer->>Grid API: All clearings posted
    Grid API->>Client Webhook: CARD_TRANSACTION.SETTLED (CardTransaction)

    alt Merchant refund
        Card Issuer->>Grid API: Refund posted
        Grid API->>Client Webhook: CARD_TRANSACTION.REFUNDED (CardTransaction)
    end

    alt Pull or confirmation failure
        Card Issuer->>Grid API: Settlement posted, pull failed
        Grid API->>Client Webhook: CARD_TRANSACTION.EXCEPTION (CardTransaction)
    end

    Client Webhook-->>Grid API: 200 OK (or 409 if duplicate)

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Card Issuer
    participant Grid API
    participant Client Webhook

    Card Issuer->>Grid API: Authorization approved
    Grid API->>Client Webhook: CARD_TRANSACTION.AUTHORIZED (CardTransaction)

    Card Issuer->>Grid API: Partial clearing posted
    Grid API->>Client Webhook: CARD_TRANSACTION.PARTIALLY_SETTLED (CardTransaction)

    Card Issuer->>Grid API: All clearings posted
    Grid API->>Client Webhook: CARD_TRANSACTION.SETTLED (CardTransaction)

    alt Merchant refund
        Card Issuer->>Grid API: Refund posted
        Grid API->>Client Webhook: CARD_TRANSACTION.REFUNDED (CardTransaction)
    end

    alt Pull or confirmation failure
        Card Issuer->>Grid API: Settlement posted, pull failed
        Grid API->>Client Webhook: CARD_TRANSACTION.EXCEPTION (CardTransaction)
    end

    Client Webhook-->>Grid API: 200 OK (or 409 if duplicate)

Loading

_{Reviews (2): Last reviewed commit: "Complete card-transaction webhook exampl..." | Re-trigger Greptile}

[AaryamanBhute]

@greptile review

[AaryamanBhute]

Merge activity

• Jul 15, 6:09 PM UTC: @AaryamanBhute merged this pull request with Graphite.