Uh oh!
There was an error while loading. Please reload this page.
docs: surface KYC/KYB sections in the ToC, add data requirements and verification-issue webhooks - #864
Conversation
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
lightspark-bot
commented
Aug 25, 2026
This stack of pull requests is managed by Graphite. Learn more about stacking. |
Greptile SummaryThis PR adds an implementation plan for exposing regulated and unregulated KYB content in Mintlify tables of contents and documenting actionable verification webhooks.
Confidence Score: 2/5The plan should not be merged until its webhook event vocabulary, regulated-snippet heading hierarchy, and unusable markdown-lint verification step are corrected. Following the plan as written would document a webhook event excluded by the verification webhook schema, preserve an invalid heading jump across all four target pages, and leave a required verification command unable to run. Files Needing Attention: docs/plans/2026-08-25-kyb-docs-toc-and-verification-webhooks.md
|
| Filename | Overview |
|---|---|
| docs/plans/2026-08-25-kyb-docs-toc-and-verification-webhooks.md | The plan is detailed, but it includes a webhook type excluded by the payload schema, creates a heading-level jump it explicitly prohibits, and requires an unavailable lint command. |
Prompt To Fix All With AI
### Issue 1
docs/plans/2026-08-25-kyb-docs-toc-and-verification-webhooks.md:66
**Invalid verification webhook event**
When an integrator follows this event table, they implement `VERIFICATION.READY_FOR_VERIFICATION`, but the verification webhook schema does not include that event type, causing documentation and handlers to advertise a delivery that cannot occur.
### Issue 2
docs/plans/2026-08-25-kyb-docs-toc-and-verification-webhooks.md:14-19
**Regulated heading hierarchy skips**
When `<KycRegulated />` is placed directly below the proposed `## Regulated Platforms` heading, its first heading is `#### Creating Customers via Direct API`, preserving the `##` to `####` jump that this plan explicitly requires the implementation to eliminate across all four pages.
### Issue 3
docs/plans/2026-08-25-kyb-docs-toc-and-verification-webhooks.md:145
**Markdown lint command is unavailable**
When the required `make lint-markdown` check runs, the Make target invokes `npm run lint:markdown`, but `package.json` defines no such script, causing the plan's prescribed validation to fail before linting the changed documentation.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.Reviews (1): Last reviewed commit: "plan: un-collapse KYB regulated/unregula..." | Re-trigger Greptile
📌 Bolt Status 2026-08-27 22:54:23 UTC — ⚡ Agent |
| |---|---|---| | ||
| | `VERIFICATION.RESOLVE_ERRORS` | Blocked on missing or rejected data | Resolve every entry in `errors`, then re-submit | | ||
| | `VERIFICATION.PENDING_MANUAL_REVIEW` | A reviewer is looking at it | None — wait | | ||
| | `VERIFICATION.READY_FOR_VERIFICATION` / `IN_PROGRESS` | Accepted, provider is running checks | None — wait | |
There was a problem hiding this comment.
When an integrator follows this event table, they implement VERIFICATION.READY_FOR_VERIFICATION, but the verification webhook schema does not include that event type, causing documentation and handlers to advertise a delivery that cannot occur.
Knowledge Base Used:Webhooks and event delivery
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/plans/2026-08-25-kyb-docs-toc-and-verification-webhooks.md
Line: 66
Comment:
**Invalid verification webhook event**
When an integrator follows this event table, they implement `VERIFICATION.READY_FOR_VERIFICATION`, but the verification webhook schema does not include that event type, causing documentation and handlers to advertise a delivery that cannot occur.
**Knowledge Base Used:**[Webhooks and event delivery](https://app.greptile.com/lightspark/-/custom-context/knowledge-base/lightsparkdev/grid-api/-/docs/webhooks-api.md)---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.There was a problem hiding this comment.
Good catch, and a subtle one — fixed. VERIFICATION.READY_FOR_VERIFICATION is in the WebhookType enum, which is what made it look deliverable, but VerificationWebhook.yaml omits it from the payload schema. Documenting it would have had integrators writing a handler branch that can never fire. The snippet now lists only the five events the payload schema can actually carry: RESOLVE_ERRORS, PENDING_MANUAL_REVIEW, IN_PROGRESS, APPROVED, REJECTED. I check the event list against that enum programmatically now, so the two can't drift.
| `###`/`####`) because the shared snippets already carry their own `###` (`Hosted KYC and KYB Link | ||
| Flow`, `Direct API Onboarding`) and `####` headings — putting the new section headings at `##` | ||
| makes those snippet headings nest as proper ToC children on every page without editing the shared | ||
| snippets or introducing per-page heading levels the snippets can't satisfy. Two pages | ||
| (`global-p2p`, `rewards`) need small local reshuffles so the new `##` sections don't swallow | ||
| sibling `###` content that isn't about regulated/unregulated platforms. |
There was a problem hiding this comment.
When <KycRegulated /> is placed directly below the proposed ## Regulated Platforms heading, its first heading is #### Creating Customers via Direct API, preserving the ## to #### jump that this plan explicitly requires the implementation to eliminate across all four pages.
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/plans/2026-08-25-kyb-docs-toc-and-verification-webhooks.md
Line: 14-19
Comment:
**Regulated heading hierarchy skips**
When `<KycRegulated />` is placed directly below the proposed `## Regulated Platforms` heading, its first heading is `#### Creating Customers via Direct API`, preserving the `##` to `####` jump that this plan explicitly requires the implementation to eliminate across all four pages.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
There was a problem hiding this comment.
Right, and I'd missed it — fixed. kyc-regulated.mdx opened with #### Creating Customers via Direct API, so anchoring the section at ## would have left an h2 → h4 jump on all four pages. Demoted that heading to ###, which is the level its siblings in kyc-unregulated.mdx already use. I verified the hierarchy programmatically with the snippets expanded inline: all four pages are now monotonic with zero jumps.
| - [ ] Every page still imports exactly the snippets it renders, and renders every snippet it imports | ||
| - [ ] Heading hierarchy is monotonic on each page (no `##` → `####` jumps); snippet `###`/`####` | ||
| headings sit under the new `##` sections | ||
| - [ ] `make lint-markdown` passes |
There was a problem hiding this comment.
When the required make lint-markdown check runs, the Make target invokes npm run lint:markdown, but package.json defines no such script, causing the plan's prescribed validation to fail before linting the changed documentation.
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/plans/2026-08-25-kyb-docs-toc-and-verification-webhooks.md
Line: 145
Comment:
**Markdown lint command is unavailable**
When the required `make lint-markdown` check runs, the Make target invokes `npm run lint:markdown`, but `package.json` defines no such script, causing the plan's prescribed validation to fail before linting the changed documentation.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.There was a problem hiding this comment.
Confirmed — I ran it and it fails: the Make target calls npm run lint:markdown, which package.json doesn't define. Worth noting it fails the same way on main, so it's a pre-existing repo bug rather than something this PR introduces, and fixing the build config felt out of scope for a docs change. I've dropped it as a gate here and used npx @redocly/cli lint openapi.yaml (passes, spec untouched) plus a real mint dev render with a DOM-level ToC check instead. Probably worth a separate fix if markdown linting is meant to be running in this repo.
⚡ Revision log — updated in place, latest first. Revision 1Implemented the approved plan, plus the KYC/KYB data requirements @pengying asked for.
|
1af5fff to
7875e56ComparePreview deployment for your docs. Learn more about Mintlify Previews.
|
…verification-issue webhooks Replace the Regulated/Unregulated AccordionGroup with regular sections on all four configuring-customers pages so they appear in the right-hand table of contents, with the shared snippets' own headings nested beneath. Add two shared snippets: the customer information to collect for KYC and KYB, and how to handle the VERIFICATION.* webhooks that fire when a verification is blocked, including how to read each error and resolve it. Co-Authored-By: pengying <pengying@users.noreply.github.com>
7875e56 to
9b17d18Compare⚡ Review ledger Round 1 — Greptile (3 × P1, all valid)
|
Summary
Two changes to the KYC/KYB onboarding docs, plus the customer data requirements.
1. Regulated / Unregulated are now real sections. Both blocks were wrapped in an
<AccordionGroup>on all fourconfiguring-customerspages, so their content was collapsed by default and never reached the right-hand table of contents. They are now regular##sections, and the shared snippets' own headings nest beneath them as ToC children.2. Verification-issue webhooks are documented. The guides covered only the terminal
CUSTOMER.KYC_*/CUSTOMER.KYB_*decisions — which tell an integrator that a customer was rejected, but not what to send to fix it. TheVERIFICATION.*events carry theerrorsarray naming each unmet requirement, and none of that was documented. A new snippet covers the events, how to read aVerificationError(resourceId,type,field,acceptedDocumentTypes,reason), how to resolve all 22 error types, and which ones are compliance outcomes that re-submitting will never clear.3. What to collect for KYC and KYB. A new snippet listing the customer information required for each customer type, with the KYB half reusing the existing requirements snippet that mirrors the
POST /verificationsdescription.Screenshot
The table of contents on
payouts-and-b2b, with the previously-collapsed sections now listed:Changes: 7 files
mintlify/snippets/kyc/verification-webhooks.mdx(new) — theVERIFICATION.*events, reading an error, resolving each error type, re-submitting, and a handler examplemintlify/snippets/kyc/customer-data-requirements.mdx(new) — KYC and KYB collection requirementsmintlify/snippets/kyc/kyc-regulated.mdx— one heading demoted####→###(see note below)configuring-customerspages (global-p2p,payouts-and-b2b,ramps,rewards) — accordions replaced with##sections; new snippets rendered at the end of the KYC/KYB sectionpayouts-and-b2bpreviously rendered no webhook snippet at all, so its KYC/KYB section now gains the existingKycWebhookscontent as well.Test plan
No OpenAPI files were touched, so there is no rebundle in this diff.
mint devand extracted the actual ToC from the DOM on all four pages — "Regulated Platforms" and "Unregulated Platforms" appear as entries, with the snippet subheadings nested beneath. Screenshot above.h2 → h4jumps.VerificationErrorTypevalues are covered, the event list exactly matches theVerificationWebhookpayload enum, and the document types, EDD fields, and individual-customer fields all resolve to real schema entries.npx @redocly/cli lint openapi.yamlpasses (unchanged, as expected).Notes on the Greptile review of the plan
All three P1s were valid and are fixed:
VERIFICATION.READY_FOR_VERIFICATIONis not deliverable. Correct, and a genuinely easy trap: the value is in theWebhookTypeenum, but theVerificationWebhookpayload schema omits it. Documenting it would have had integrators writing a handler branch that can never fire. The snippet documents only the five events the payload schema can actually carry.kyc-regulated.mdxopened with a####, which would have left anh2 → h4jump on all four pages. That heading is demoted to###; verified monotonic above.make lint-markdownis unavailable. Correct. The Make target callsnpm run lint:markdown, whichpackage.jsondoesn't define — it fails onmaintoo. That's a pre-existing repo bug rather than something this PR introduces, so I've left it alone and used the OpenAPI lint plus the render check as the gates instead. Worth a separate fix if markdown linting is meant to be running in this repo.Public
Documents the customer information required for KYC and KYB, and how to handle the verification webhooks Grid sends when a verification is blocked.