feat(spec): add INCOMING_PAYMENT.PROCESSING to the webhook contract

[shreyav]

Note

Bottom of a three-PR stack, based on main and mergeable on its own. #856 and #857 sit on top of it. Deliberately isolated so the sparkcore fix that depends on this enum isn't blocked behind the docs work above.

The bug

WebhookType describes itself as dot-notation that "lets consumers route purely on type without inspecting data.status".

The incoming family breaks that promise. _get_incoming_webhook_type (sparkcore/grid/webhooks/webhook_handler.py:142) collapses four states onto one event:

case (CREATED | PENDING | PROCESSING | SENT):
    return WebhookType.INCOMING_PAYMENT_DOT_PENDING

The outgoing twin 24 lines above maps PROCESSING to its own event. So a pull into an internal account fires INCOMING_PAYMENT.PENDING twice, and the second payload carries "status": "PROCESSING" inside an envelope typed PENDING — exactly the inspect-data.status case the contract says consumers should not need.

Likely why it went unnoticed: the receive-operation path (ordinary deposits) does not appear to reach PROCESSING/SENT, so the collapse was harmless. GK.GRID_INCOMING_TRANSACTION_REFACTOR then routed send operations — which do pass through those states — into this function without extending it.

This PR

Contract only. Adds INCOMING_PAYMENT.PROCESSING to WebhookType and to the IncomingPaymentWebhook type enum, mirroring the outgoing family.

sparkcore does not emit the event yet. Its WebhookType is generated from this spec, so this has to land before the emission fix can reference the new member.

Follow-up in webdev, after this merges

1. Regenerate the grid-api Python SDK so WebhookType.INCOMING_PAYMENT_DOT_PROCESSING exists.
2. Split PROCESSING | SENT out of the PENDING case in _get_incoming_webhook_type. SENT belongs with PROCESSING, not PENDING — gen_convert_send_op_to_incoming_transaction already maps SENT onto status PROCESSING (transaction.py:891), so that is what makes the envelope agree with its payload.

Note for whoever picks that up: it changes behavior for existing integrators, who currently receive two PENDING events and will start receiving PENDING then PROCESSING.

A smaller instance of the same collapse is out of scope here: _get_incoming_webhook_type also folds EXPIRED into INCOMING_PAYMENT.FAILED.

Validation

Check	Result
make lint	exit 0 — 0 errors
make build + bundle sync	openapi.yaml / mintlify/openapi.yaml in sync
oasdiff 1.16.0 vs main	no breaking changes — adding an enum value widens the contract

---

Generated by Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Grid	🟢 Ready	View Preview	Aug 24, 2026, 4:12 AM

[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		Aug 24, 2026 4:11am
grid-wallet-demo	Ignored		Aug 24, 2026 4:11am

[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 processing status to incoming payment webhook events

kotlin

feat(api): add INCOMING_PAYMENT_PROCESSING to IncomingPaymentWebhookEvent

openapi

feat(api): add PROCESSING event to incoming payments

php

feat(api): add PROCESSING status to IncomingPaymentWebhookEvent

python

feat(api): add INCOMING_PAYMENT.PROCESSING event type to incoming payment webhooks

ruby

feat(api): add processing status to incoming payment webhook events

typescript

feat(api): add INCOMING_PAYMENT.PROCESSING event type to webhooks

Edit this comment to update them. They will appear in their respective SDK's changelogs.

✅ grid-typescript studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → build ✅ → lint ❗ → test ✅

npm install https://pkg.stainless.com/s/grid-typescript/a7f62b15c0bfe144bf0c9a2ff43161e9d973ff1f/dist.tar.gz

✅ grid-openapi studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️

✅ grid-ruby studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → build ✅ → lint ✅ → test ✅

✅ grid-go studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → build ✅ → lint ❗ → test ❗

go get github.com/stainless-sdks/grid-go@bdfa2adbbaba177343b442cd43af15af8eb8458a

✅ grid-kotlin studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → build ✅ → lint ✅ → test ❗

✅ grid-python studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → build ✅ → lint ❗ → test ❗

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

✅ grid-php studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → lint ✅ → test ✅

✅ grid-cli studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
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-08-24 04:16:38 UTC

[greptile-apps]

Greptile Summary

Adds INCOMING_PAYMENT.PROCESSING to the shared webhook type registry and incoming-payment payload contract, preparing generated clients for a subsequent emitter change.

• Updates both modular webhook schemas with the new event value.
• Synchronizes the generated root and Mintlify OpenAPI bundles.
• Keeps the shared event registry and incoming-payment schema narrowing aligned.

Confidence Score: 5/5

The PR appears safe to merge because the additive event value is consistently represented across the authoritative schemas and generated bundles.

The shared webhook registry and incoming-payment payload enum remain aligned, no additional discriminator or registry requires updating, and the generated contracts mirror the modular source.

Important Files Changed

Filename	Overview
openapi/components/schemas/webhooks/WebhookType.yaml	Adds the processing event to the authoritative shared webhook type registry.
openapi/components/schemas/webhooks/IncomingPaymentWebhook.yaml	Adds the same event to the incoming-payment webhook's narrowed type enum.
openapi.yaml	Correctly mirrors both source-schema additions in the generated bundled contract.
mintlify/openapi.yaml	Keeps the Mintlify contract bundle synchronized with the generated root contract.

_{Reviews (1): Last reviewed commit: "feat(spec): add INCOMING_PAYMENT.PROCESS..." | Re-trigger Greptile}