feat(spec): add INCOMING_PAYMENT.PROCESSING to the webhook contract - #858
Merged
Conversation
WebhookType describes itself as dot-notation that "lets consumers route purely on type without inspecting data.status". The incoming family breaks that promise: it has no PROCESSING event, so sparkcore's _get_incoming_webhook_type collapses CREATED, PENDING, PROCESSING and SENT onto INCOMING_PAYMENT.PENDING, while the outgoing equivalent gives PROCESSING its own event. A pull into an internal account therefore fires 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. Adds the value to WebhookType and to the IncomingPaymentWebhook type enum, mirroring the outgoing family. Contract only: sparkcore does not emit the event yet, and its WebhookType is generated from this spec, so this has to land before the emission fix can reference the new member. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TxsyZEDjQDt97rR3kd2kxv
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
|
The latest updates on your projects. Learn more about Vercel for GitHub. 2 Skipped Deployments
|
Contributor
✱ Stainless preview builds for gridThis PR will update the cli go kotlin openapi php python ruby typescript
|
shreyav
marked this pull request as ready for review
August 24, 2026 06:30
Contributor
Greptile SummaryAdds
Confidence Score: 5/5The 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.
|
| 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
wuvictor-95
approved these changes
Aug 24, 2026
shreyav
added a commit
that referenced
this pull request
Aug 24, 2026
…857) > [!NOTE] > **Top of a three-PR stack:** #858 (spec) → #856 (transfer deprecation) → this. Base is `claude/transfer-api-deprecation-docs-6ycamq`, so the diff here is only the 3 files below. Each merge retargets this automatically. ## The gap Nothing in the docs said whether a given transfer produces an `INCOMING` or an `OUTGOING` transaction. Worse, the Transaction Lifecycle page contained **zero occurrences of the word "incoming"** — it described only the outgoing flow, despite `INCOMING_PAYMENT.*` webhooks existing and being referenced from six other pages. ## The rule The type is keyed on the **destination**, regardless of source: | Destination | `type` | Webhook family | |---|---|---| | Internal account | `INCOMING` | `INCOMING_PAYMENT.<STATUS>` | | External account | `OUTGOING` | `OUTGOING_PAYMENT.<STATUS>` | | UMA address | `OUTGOING` | `OUTGOING_PAYMENT.<STATUS>` | Consequences worth spelling out, and now spelled out: - A pull from an external account into an internal account is `INCOMING`, even though the platform initiated it. - A transfer between two internal accounts is `INCOMING`. - A deposit that lands by paying an internal account's payment instructions is `INCOMING`, as is a payment received at a customer's UMA address. This mirrors the dispatch in `gen_convert_to_transaction` (`sparkcore/grid/objects/transaction.py:159`), which routes `EntGridReceiveOperation` to incoming unconditionally and branches a send operation on `gen_send_op_destination_is_internal_account`. That helper carries the same truth table in its docstring at `transaction.py:738`. The branch is gated on `GK.GRID_INCOMING_TRANSACTION_REFACTOR`, which is rolled out, so the table describes current behavior for all platforms. ## Changes - **`transaction-lifecycle.mdx`** — new **Incoming or outgoing** section at the top, ahead of the flow sections, since the type decides which lifecycle and webhook family apply. - **`transaction-lifecycle.mdx`** — split the webhook event table into outgoing and incoming families. The incoming list was missing entirely. Its `INCOMING_PAYMENT.PROCESSING` row corresponds to the enum value added in #858. - **`terminology.mdx`** — said the type was "from the platform's perspective", which does not tell a reader how to predict it. Now states the rule. - **`list-transactions.mdx`** — the *Filter by transaction type* section had the reader choosing `type=INCOMING|OUTGOING` with no way to know which their payout is. Now states the rule and links to the table. ## Two things this PR previously got wrong Recorded because both were corrected in place and a reviewer reading only the head would not see them: 1. An early revision claimed incoming transactions have no `PROCESSING` **state**. False — they do; both incoming converters map `display_status` through, and `gen_convert_send_op_to_incoming_transaction` maps `SENT` onto `PROCESSING` explicitly (`transaction.py:891`). Only the *webhook event* is missing. 2. The next revision then explained that missing event as an intentional design difference, which would have enshrined a bug. It is a sparkcore bug; #858 adds the enum and describes the emission fix. ## Validation - `make lint` exits 0 — 663 problems, unchanged from baseline (all pre-existing) - Docs-only: no files under `openapi/`, so the bundle, oasdiff, and SDK generation are untouched by this PR - The `#incoming-or-outgoing` anchor is linked from `list-transactions.mdx`; the heading carries no punctuation, so the slug is unambiguous --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Note
Bottom of a three-PR stack, based on
mainand 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
WebhookTypedescribes itself as dot-notation that "lets consumers route purely on type without inspectingdata.status".The incoming family breaks that promise.
_get_incoming_webhook_type(sparkcore/grid/webhooks/webhook_handler.py:142) collapses four states onto one event:The outgoing twin 24 lines above maps
PROCESSINGto its own event. So a pull into an internal account firesINCOMING_PAYMENT.PENDINGtwice, and the second payload carries"status": "PROCESSING"inside an envelope typedPENDING— exactly the inspect-data.statuscase 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_REFACTORthen routed send operations — which do pass through those states — into this function without extending it.This PR
Contract only. Adds
INCOMING_PAYMENT.PROCESSINGtoWebhookTypeand to theIncomingPaymentWebhooktypeenum, mirroring the outgoing family.sparkcore does not emit the event yet. Its
WebhookTypeis 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
WebhookType.INCOMING_PAYMENT_DOT_PROCESSINGexists.PROCESSING | SENTout of thePENDINGcase in_get_incoming_webhook_type.SENTbelongs withPROCESSING, notPENDING—gen_convert_send_op_to_incoming_transactionalready mapsSENTonto statusPROCESSING(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
PENDINGevents and will start receivingPENDINGthenPROCESSING.A smaller instance of the same collapse is out of scope here:
_get_incoming_webhook_typealso foldsEXPIREDintoINCOMING_PAYMENT.FAILED.Validation
make lintmake build+ bundle syncopenapi.yaml/mintlify/openapi.yamlin syncmainGenerated by Claude Code