feat: cleaning up webhooks

[pengying]

TL;DR

Updated webhook event type names to be more descriptive and consistent.

Changes defined in https://docs.google.com/document/d/1YdRboRlrwm0HKmRdyp-lbHZcfYUtJMF5NWk35vd_dZI/edit?tab=t.0

[pengying]

• feat: cleaning up webhooks #212 👈 (View in Graphite)
• main

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

[greptile-apps]

Greptile Summary

This PR updates webhook event types from simple names (e.g., INCOMING_PAYMENT, KYC_STATUS) to descriptive dot-notation (e.g., INCOMING_PAYMENT.COMPLETED, CUSTOMER.KYC_APPROVED). The new naming convention uses OBJECT.EVENT format where the prefix identifies the resource and the suffix identifies the specific event, enabling consumers to route based on type without inspecting the payload.

Key changes:

• Webhook envelope structure now uses id, type, timestamp, and data fields consistently across all webhook types
• Removed webhookId field in favor of id
• Consolidated webhook payloads under a single data field containing the full resource object
• Added new webhook schemas: CustomerKycWebhook.yaml, BulkUploadWebhook.yaml
• Updated all webhook endpoint definitions and examples to use the new structure
• Updated documentation to use .startsWith() pattern for routing webhook types

Issues found:

• Several documentation files outside the changed set still reference old webhook types (KYC_STATUS, ACCOUNT_STATUS, INVITATION_CLAIMED)
• These need to be updated to match the new naming convention for consistency

The implementation is clean and systematic across OpenAPI schemas and webhook endpoint definitions. The changes are breaking and require webhook consumers to update their parsing logic.

Confidence Score: 4/5

• This PR is safe to merge after addressing documentation inconsistencies
• The webhook schema changes are comprehensive and well-executed across all OpenAPI files. However, several documentation files still reference old webhook types, which could confuse integrators. Once these docs are updated, the PR will be fully consistent.
• mintlify/ramps/platform-tools/webhooks.mdx and mintlify/snippets/creating-customers/customers.mdx need updates to use new webhook types

Important Files Changed

Filename	Overview
openapi/components/schemas/webhooks/WebhookType.yaml	Webhook types updated to dot-notation (e.g., OUTGOING_PAYMENT.COMPLETED). Clean, well-structured change.
openapi/components/schemas/webhooks/BaseWebhook.yaml	Added required data field, removed discriminator mapping. Consistent with new webhook envelope structure.
openapi/components/schemas/webhooks/CustomerKycWebhook.yaml	New schema replacing KycStatusWebhook. Uses CUSTOMER.* naming pattern with KYC event types.
mintlify/snippets/webhooks.mdx	Updated code examples to use type.startsWith() pattern for dot-notation types. Changed webhookId to id.
mintlify/ramps/platform-tools/webhooks.mdx	Contains outdated webhook type references (KYC_STATUS, ACCOUNT_STATUS) that need updating to new dot-notation format
mintlify/snippets/creating-customers/customers.mdx	Contains old KYC_STATUS webhook example that needs updating to CUSTOMER.KYC_APPROVED format

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Webhook Event] --> B{Old Schema}
    B --> C[Single type field<br/>e.g., INCOMING_PAYMENT]
    B --> D[Resource-specific fields<br/>transaction, invitation, etc.]
    
    E[Webhook Event] --> F{New Schema}
    F --> G[Dot-notation type<br/>e.g., INCOMING_PAYMENT.COMPLETED]
    F --> H[Standardized envelope<br/>id, type, timestamp, data]
    H --> I[data contains full resource<br/>same as GET endpoint]
    
    J[Migration Impact] --> K[Breaking Change]
    K --> L[Consumers must update<br/>type checking logic]
    K --> M[Use .startsWith for routing]
    K --> N[Parse data field<br/>instead of top-level fields]
    
    style B fill:#ffcccc
    style F fill:#ccffcc
    style K fill:#ffffcc

Loading

_{Last reviewed commit: 8c37e14}

[greptile-apps]

_{24 files reviewed, 7 comments}

_{Edit Code Review Agent Settings | Greptile}

[github-actions]

✱ Stainless preview builds

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

kotlin

feat: cleaning up webhooks

openapi

feat(api): move test webhook to sandbox, restructure webhook payloads, update types to dot-notation

python

chore(api): move webhooks resource to sandbox namespace

typescript

feat(api): move sendTest method from webhooks to sandbox.webhooks

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

✅ grid-openapi studio · code · diff

Your SDK build was successful, but this did not represent a regression.
generate ✅

✅ grid-python studio · code · diff

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

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

✅ grid-kotlin studio · code · diff

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

✅ grid-typescript studio · code · diff

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

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

---

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-02-28 20:14:30 UTC

[greptile-apps]

Additional Comments (3)

openapi/components/schemas/invitations/UmaInvitation.yaml, line 1
Update description text from INVITATION_CLAIMED webhook to INVITATION.CLAIMED webhook to match the new dot-notation naming convention.

      platform once the INVITATION.CLAIMED webhook is received. If the inviter

_{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!}

---

openapi/components/schemas/invitations/UmaInvitationCreateRequest.yaml, line 1
Update description text from INVITATION_CLAIMED webhook to INVITATION.CLAIMED webhook to match the new dot-notation naming convention.

      INVITATION.CLAIMED webhook is received. If the inviter

_{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!}

---

openapi/paths/invitations/invitations_{invitationCode}_claim.yaml, line 1
Update description text from An INVITATION_CLAIMED webhook to An INVITATION.CLAIMED webhook to match the new dot-notation naming convention.

    3. An INVITATION.CLAIMED webhook is triggered to notify the platform that

[greptile-apps]

Additional Comments (5)

openapi/components/schemas/invitations/UmaInvitation.yaml, line 59
Update webhook name reference from INVITATION_CLAIMED to INVITATION.CLAIMED

      platform once the INVITATION.CLAIMED webhook is received. If the inviter

---

mintlify/ramps/platform-tools/webhooks.mdx, line 73
Update tab to use new ACCOUNT.BALANCE_UPDATED webhook type and new envelope structure with id, type, timestamp, and data fields. The current example uses the old ACCOUNT_STATUS type and structure.

---

mintlify/ramps/platform-tools/webhooks.mdx, line 88
Update tab to use new CUSTOMER.KYC_* webhook types (e.g., CUSTOMER.KYC_APPROVED) and new envelope structure. The current example uses the old KYC_STATUS type and structure. See mintlify/snippets/kyc/kyc-webhooks.mdx for the updated structure.

---

mintlify/ramps/platform-tools/webhooks.mdx, line 248
Update to use new webhook type with dot-notation

if (type === "ACCOUNT.BALANCE_UPDATED") {

_{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!}

---

mintlify/snippets/creating-customers/customers.mdx, line 170
Update webhook example to use new CUSTOMER.KYC_APPROVED type and envelope structure with id and data fields. The webhook structure has changed from having top-level fields to having a data object containing the customer resource.