docs: document the secure_payment.user_event webhook

[rodrigopavezi]

Problem

Platforms need a documented contract for Secure Payment Page payer-funnel events. This is part of REQ-291.

Proposed Solution

• Document secure_payment.user_event, its three userEvent values, payload, and field semantics.
• Add the event to the event catalog, quickstart, and reconciliation routing example.
• Pass the webhook delivery ID to each business handler as its idempotency key; consumers persist that key atomically with their own business update.

Considerations

• The API PR merges first, so platforms receive the event before the public docs describe it.
• This is best-effort payer-funnel telemetry, not a settlement signal. Use payment.confirmed for reconciliation.
• properties is browser-provided telemetry. When the Secure Payment Page includes wallet information, it uses wallet_address_hashed rather than a raw address.
• Other currently undocumented events (client_id.linked, secure_payment.access_rejected, kyt.screening.completed) remain out of scope.

[mintlify]

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

Project	Status	Preview	Updated (UTC)
request-network	🟢 Ready	View Preview	Aug 6, 2026, 12:31 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[greptile-apps]

Greptile Summary

The PR documents the secure_payment.user_event payer-funnel webhook and updates the related event catalogs and reconciliation guidance.

• Defines the three userEvent values, payload fields, telemetry limitations, and privacy treatment.
• Adds the event to the feature catalog, API reference, quickstart, and reconciliation routing example.
• Replaces cache-based delivery claims with business-operation idempotency guidance and a transactional database example.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
api-features/webhooks-events.mdx	Adds the payer-funnel event to the event-category overview and supported use cases.
api-reference/webhooks.mdx	Defines the new webhook's event values, payload example, delivery behavior, telemetry limitations, and wallet-data privacy semantics.
use-cases/quickstart.mdx	Adds the new event to the supported webhook catalog with a clear non-settlement warning.
use-cases/webhook-reconciliation.mdx	Adds routing for the new event and revises the example to use durable, transactionally recorded delivery IDs for business-operation idempotency.

Sequence Diagram

sequenceDiagram
    participant Browser as Secure Payment Page
    participant API as Request Network API
    participant Webhook as Platform Webhook
    participant Store as Business Store
    Browser->>API: Report payer-funnel step
    API->>Webhook: secure_payment.user_event + delivery ID
    Webhook->>Webhook: Verify raw-body HMAC
    Webhook->>Store: Apply telemetry update and delivery ID atomically
    alt First delivery
        Store-->>Webhook: Update committed
    else Repeated delivery
        Store-->>Webhook: Successful no-op
    end
    Webhook-->>API: 200 OK

Loading

_{Reviews (7): Last reviewed commit: "docs: demonstrate atomic webhook idempot..." | Re-trigger Greptile}

[MantisClone]

Optimistically Approved 👍 pending comment resolution 🚧

Requested change:

• Add a prominent note that secure_payment.user_event is best-effort browser telemetry. The browser request can still fail before the API accepts it. Webhook retries start only after that acceptance. Consumers must not treat an absent event as evidence that the payer did not take the step, and must use payment.confirmed for settlement/reconciliation.
• Qualify the wallet-address sentence: when the SPP includes wallet information in event properties, it uses wallet_address_hashed rather than a raw wallet address.

Why:

The current preview correctly says the fields are non-authoritative but promises the normal retry behavior without the pre-ingestion loss boundary. The wallet-address statement should describe SPP behavior precisely.

If unaddressed:

A platform can build drop-off, notification, or reconciliation logic on an intentionally incomplete event stream, or rely on an over-broad privacy guarantee.