docs: add webhooks integration guide#87
Merged
Merged
Conversation
Adds payments/webhooks covering event types, payload contract, delivery guarantees (at-least-once, ordering, ~28h retry schedule), signature verification, test delivery, and go-live checklist. Nav item placed directly after Test mode in both doc versions. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Cali93
marked this pull request as ready for review
July 21, 2026 13:40
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
- Remove nav entry; page is accessible by direct URL only - Remove rollout disclaimer - Trim page description - Reframe webhooks vs. polling: webhooks notify, polling decides; relax poll interval (e.g. 5s) and confirm state on webhook receipt - Replace all em-dashes with natural connectors Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Replace Svix-library examples with dependency-free stdlib implementations (Node.js, Python, Go, Java, C#, PHP, Ruby), document the HMAC scheme explicitly, and add a copyable agent prompt with the Svix test vector for one-shot implementation. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The full prompt no longer renders on the page; it lives in copy-agent-prompt.js (Mintlify injects content-directory .js files on every page) and is copied to the clipboard by a Copy prompt button via event delegation. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
xikimay
previously requested changes
Jul 22, 2026
xikimay
left a comment
xikimay
left a comment
There was a problem hiding this comment.
Thanks for the doc! I have some suggestions and some corrections
- Reframe polling as primary, webhooks as enhancement; no API call needed inside the handler (full versioned snapshots) - Drop the follow-up GET rule from out-of-order section - Use the golden payment-succeeded fixture verbatim (includes fee) - Add fee.kind extensibility and failure/cancellation_reason rules - Add 15s response deadline and 5-day endpoint auto-disable - Recommend a periodic reconciliation job over manual recovery - Add processing->cancelled and created->failed diagram edges - Note payment.settled carries status succeeded - tx_id is chain-specific and nullable - Rename signature headers to white-labeled webhook-* - Agent prompt: persist/enqueue before responding 200 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
Author
riveign
reviewed
Jul 22, 2026
xikimay
reviewed
Jul 22, 2026
xikimay
approved these changes
Jul 22, 2026
xikimay
left a comment
xikimay
left a comment
There was a problem hiding this comment.
LGTM. One dependency before merging: the white-labeled webhook-* headers documented here require the Svix plan upgrade and the white-label setting on all three environments. Deliveries still send svix-* until that lands.
- Intro frames webhooks as enhancing the integration (riveign) - Agent copy-prompt option now comes before the manual implementations in the verify step (riveign) - Go-live checklist drops the status-poll-before-irreversible leftover (xikimay) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
xikimay
reviewed
Jul 22, 2026
| <Step title="Register the endpoint" stepNumber="1"> | ||
|
|
||
| 1. In the [dashboard](https://merchant.pay.walletconnect.com), make sure the **Test / Live** selector matches the mode you're setting up, since endpoints are configured separately per mode. | ||
| 2. Open **Webhooks** and add your endpoint: a publicly reachable **HTTPS** URL, and the event types you want (all seven by default). |
There was a problem hiding this comment.
Follow-up for later, no change needed now: on the upgraded plan, deliveries come from a guaranteed static set of source IPs (EU region for us). Partners with strict firewalls will ask for the allowlist, so this register-endpoint step is where we should document them.
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
3 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.
Summary
Adds a Webhooks page (
payments/webhooks) to the Payments docs, placed in the nav directly after Test mode (in both the2026-02-18and2026-02-19.previewversions).The guide covers:
payment.*event types with a lifecycle diagramid,type,api_version,created_at,data), full-snapshot semantics, a completepayment.succeededexample, and a warning to parse tolerantly (additive-only contract)id), out-of-order delivery (comparepayment_state_version), 2xx acknowledgment, and the ~28-hour retry schedule with manual recovery after exhaustiondata.livecheck before real fulfillmentFacts (retry schedule, event types, payload fields, signature scheme, one-endpoint-per-mode, rotation window) were sourced from the Svix integration in
pay-merchant-experience(services/merchant-apipartner-webhooks module and the frozen public payload schema).🤖 Generated with Claude Code
Linear: WCPM-530
Dashboard link PR: WalletConnect/pay-merchant-experience#874
Merge dependencies
webhook-*headers instead ofsvix-*(per @xikimay approval note).