docs: document the secure_payment.user_event webhook

api-features/webhooks-events.mdx

@@ -9,7 +9,7 @@
 
 ## Event Categories
 
-The Request Network webhook system emits **12 event types** across four categories:
+The Request Network webhook system emits **13 event types** across five categories:
 
 | Category | Events |
 | --- | --- |
@@ -19,6 +19,7 @@
 | **Processing** (crypto-to-fiat) | `payment.processing` (with `subStatus`) |
 | **Request** | `request.recurring` |
 | **Compliance / Bank** | `compliance.updated`, `payment_detail.updated` |
+| **Secure Payment Page** (payer funnel) | `secure_payment.user_event` (with `userEvent`) |
 
 The `.client_id` and `.checkout` variants are emitted in addition to the base `.confirmed` / `.partial` events when the request was created via a Client ID or as a checkout / secure payment, respectively. They include extra metadata (`clientId`, `origin`).
 
@@ -47,7 +48,7 @@
 ## Key Features
 
 ### Reliability
 - **Idempotency support:** Use `x-request-network-delivery` header for duplicate detection
 - **Delivery confirmation:** Monitor `x-request-network-retry-count` header to track attempts
 
 ### Security
@@ -57,7 +58,7 @@
 
 ### Development Tools
 - **Test deliveries:** Fire test events via `POST /v1/webhook/test` (Auth API) — see [Webhooks reference](/api-reference/webhooks#testing)
 - **ngrok integration:** Receive webhooks locally during development
 - **Comprehensive logging:** Request API logs all delivery failures with attempt details
 
 ## Common Use Cases
@@ -66,7 +67,8 @@
 - **Order fulfillment:** Release goods or services immediately after payment confirmation
 - **Subscription management:** Handle `request.recurring` for automatic billing renewals
 - **Compliance workflows:** Update user permissions when `compliance.updated` shows KYC approval
 - **Real-time dashboards:** Display live payment status using `payment.processing` subStatus values
+- **Payer-funnel visibility:** Track wallet connection and signature progress on the Secure Payment Page via `secure_payment.user_event`
 
 ## Implementation
 

api-reference/webhooks.mdx

@@ -62,7 +62,7 @@
 
 | Event | Description | Context | Primary Use |
 |-------|-------------|---------|-------------|
 | `payment.confirmed` | Payment fully completed and settled | After blockchain confirmation | Complete fulfillment, release goods |
 | `payment.partial` | Partial payment received for request | Installments, partial orders | Update balance, allow additional payments |
 | `payment.failed` | Payment execution failed | Recurring payments, cross-chain transfers | Notify failure, retry logic, pause subscriptions |
 | `payment.refunded` | Payment has been refunded to payer | Cross-chain payment failures, refund scenarios | Update order status, notify customer |
@@ -89,7 +89,7 @@
 
 | Event | Description | Context | Primary Use |
 |-------|-------------|---------|-------------|
 | `payment.processing` | Crypto-to-fiat payment in progress | **subStatus values:** initiated, pending_internal_assessment, ongoing_checks, sending_fiat, fiat_sent, bounced | Track crypto-to-fiat payment status, update UI |
 
 ### Request Events
 
@@ -101,16 +101,40 @@
 
 | Event | Description | Context | Primary Use |
 |-------|-------------|---------|-------------|
 | `compliance.updated` | KYC or agreement status changed | **kycStatus values:** not_started, pending, approved, rejected, retry_required<br/>**agreementStatus values:** not_started, pending, completed, rejected, failed | Update user permissions, notify status |
 | `payment_detail.updated` | Bank account verification status updated | States: approved, failed, pending | Enable fiat payments, update profiles |
 
+### Secure Payment Page Events (payer funnel)
+
+| Event | Description | Context | Primary Use |
+|-------|-------------|---------|-------------|
+| `secure_payment.user_event` | Payer progressed through a step of the Secure Payment Page | **userEvent values:** wallet_connected, payment_sent_to_wallet, payment_approved_in_wallet | Real-time payer-funnel visibility, drop-off analytics |
+
+Sent to the same registered webhook endpoints as every other event — same Client ID scoping, `x-request-network-signature` HMAC verification, delivery headers, timeout, and 1s/5s/15s retry semantics described elsewhere on this page.
+
+The `userEvent` field distinguishes the 3 funnel steps:
+
+| `userEvent` | Meaning |
+|-------------|---------|
+| `wallet_connected` | The payer successfully connected a wallet on the secure payment page |
+| `payment_sent_to_wallet` | The payment transaction was handed to the payer's wallet for signature |
+| `payment_approved_in_wallet` | The payer approved/signed the payment in their wallet. `properties` includes the submission id (e.g. tx hash / user-operation hash) |
+
+<Note>
+`securePaymentToken` is the platform's correlation key, returned when the secure payment was created. `requestId` is present only when exactly one request is linked to the secure payment (see `requestIds` for the full list). `timestamp` is server-stamped on receipt. `occurredAt` and `properties` are **client-reported telemetry from the payer's browser** — useful for analytics, but not authoritative.
+
+`secure_payment.user_event` is best-effort browser telemetry. Navigation, network errors, or browser extensions can prevent the API from receiving it. Webhook retries begin only after the API accepts the event. Do not treat an absent event as evidence that the payer did not take the step; use `payment.confirmed` for settlement and reconciliation.
+
+When the Secure Payment Page includes wallet information in `properties`, it uses `wallet_address_hashed` rather than a raw wallet address.
+</Note>
+
 ## Security Implementation
 
 ### Signature Verification
 Every webhook includes an HMAC SHA-256 signature in the `x-request-network-signature` header:
 
 ```javascript
 import crypto from "node:crypto";
 
 function verifyWebhookSignature(rawBody, signature, secret) {
   const expectedSignature = crypto
@@ -197,8 +221,8 @@
 - `requestId` / `requestID`: Unique identifier for the payment request
 - `paymentReference`: Short reference, also unique to a request, used to link payments to the request
 - `timestamp`: ISO 8601 formatted event timestamp
 - `paymentProcessor`: Either `request-network` (crypto) or `request-tech` (fiat)
 - `payerAddress`: Resolved payer wallet — the on-chain sender for plain direct payments, or the resolved payer for recurring and intent-based flows (Secure Payment Page, LiFi, Safe, ERC-4337, multicall). `null` when it cannot be determined. Included on `payment.confirmed` and `payment.partial` events (and their `.client_id` / `.checkout` variants).
 - `payerEoaAddress`: The payer's connected wallet address. It can differ from `payerAddress` when a smart account is used. `null` when unavailable. Included on `payment.confirmed` and `payment.partial` events (and their `.client_id` / `.checkout` variants).
 
 ### Payment Confirmed
@@ -303,6 +327,27 @@
 }
 ```
 
+### Secure Payment User Event
+```json
+{
+  "event": "secure_payment.user_event",
+  "userEvent": "payment_approved_in_wallet",
+  "securePaymentToken": "spt_3fk29ax7...",
+  "requestId": "01JD3E6JD46KY4KKV7X9V0MZ7W",
+  "requestIds": ["01JD3E6JD46KY4KKV7X9V0MZ7W"],
+  "orchestratorId": "orch_12345",
+  "occurredAt": "2026-08-05T14:03:21.512Z",
+  "timestamp": "2026-08-05T14:03:22.104Z",
+  "properties": {
+    "wallet_provider": "metamask",
+    "payment_submission_id": "0x6a4f...e21b",
+    "payment_submission_id_type": "evm_tx_hash",
+    "selected_source_chain": "base",
+    "payment_type": "single"
+  }
+}
+```
+
 ## Implementation Examples
 
 For a complete working example, see [Webhook reconciliation](/use-cases/webhook-reconciliation) which implements webhook handling for payment notifications.
@@ -455,7 +500,7 @@
 ## Best Practices
 
 ### Error Handling
 - **Implement idempotency:** Use delivery IDs to prevent duplicate processing
 - **Graceful degradation:** Handle unknown event types without errors
 
 ### Performance  
@@ -476,7 +521,7 @@
 - Confirm the webhook is `active` via `GET /v1/webhook` (toggle with `PUT /v1/webhook/:id`)
 
 ### Debugging Tips
 - Use ngrok request inspector to see raw webhook data
 - Monitor retry counts in headers to identify issues
 - Fire test deliveries via `POST /v1/webhook/test`
 

use-cases/quickstart.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Quickstart"
 description: "End-to-end walkthrough — sign in to the Dashboard, create a payment destination, register a webhook, and create a hosted payment link."
 ---
 
 This guide walks through the canonical flow for receiving payments via Request Network: creating a payment destination and Client ID in the Dashboard, registering a webhook for payment notifications, and creating a payment link. Every other use-case page links back to specific steps here.
@@ -235,7 +235,7 @@
 | Header | Description |
 | --- | --- |
 | `x-request-network-signature` | HMAC-SHA256 of the raw JSON body, signed with your webhook secret |
 | `x-request-network-delivery` | Unique delivery ID — use as an idempotency key |
 | `x-request-network-retry-count` | Retry attempt number (`0`–`3`) |
 | `x-request-network-test` | `true` only for test deliveries via `/v1/webhook/test` |
 
@@ -293,7 +293,7 @@
 | `totalAmountPaid` | Cumulative amount paid so far |
 | `expectedAmount` | The total amount expected |
 | `txHash` | On-chain transaction hash |
 | `network` | The blockchain network |
 | `currency` | The token used for payment |
 
 ### All supported webhook events
@@ -308,10 +308,11 @@
 | `payment.partial.checkout` | Secure-payment-scoped variant of `payment.partial` |
 | `payment.failed` | Payment failed |
 | `payment.refunded` | Payment refunded |
 | `payment.processing` | Offramp processing started |
 | `request.recurring` | A recurring request fired |
 | `payment_detail.updated` | Payment detail metadata changed |
 | `compliance.updated` | Compliance status changed |
+| `secure_payment.user_event` | Payer progressed through a Secure Payment Page step (`userEvent`: `wallet_connected`, `payment_sent_to_wallet`, `payment_approved_in_wallet`) — funnel telemetry, not a settlement signal |
 
 ## Step 5: Create a Secure Payment (Payment Link)
 

use-cases/webhook-reconciliation.mdx

@@ -9,7 +9,7 @@
 
 **Audience:** any backend integrating Request Network where payment events drive state changes downstream.
 
-## The 12 events
+## The 13 events
 
 | Category | Event | When it fires |
 | --- | --- | --- |
@@ -21,10 +21,11 @@
 | | `payment.partial.client_id` | Client ID-scoped partial |
 | Payment (Checkout) | `payment.confirmed.checkout` | Same as `payment.confirmed`, request originated from a Secure Payment link |
 | | `payment.partial.checkout` | Secure Payment-scoped partial |
 | Processing | `payment.processing` | Crypto-to-fiat offramp in progress (with detailed `subStatus`) |
 | Request | `request.recurring` | A new recurring billing cycle fired |
 | Compliance | `compliance.updated` | KYC or agreement status changed |
 | Bank details | `payment_detail.updated` | Bank account verification status changed |
+| Secure Payment Page | `secure_payment.user_event` | Payer progressed through a step of the Secure Payment Page (`userEvent`: `wallet_connected`, `payment_sent_to_wallet`, `payment_approved_in_wallet`) — funnel telemetry, **not** a settlement signal |
 
 For the full payload schemas, see the [Webhooks reference](/api-reference/webhooks).
 
@@ -48,15 +49,13 @@
 
 ## Handler — reference implementation
 
-A signature-verifying Express handler with idempotency. Hardened for production: verifies against the **raw** body, uses constant-time comparison, deduplicates on `x-request-network-delivery`.
+A signature-verifying Express handler. It verifies against the **raw** body, uses constant-time comparison, passes the delivery ID to business handlers as their idempotency key, and lets Request Network retry a failed handler.
 
 ```typescript
 import { createHmac, timingSafeEqual } from "node:crypto";
 import express from "express";
-import { Redis } from "ioredis";
 
 const app = express();
-const redis = new Redis(process.env.REDIS_URL!);
 const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET!;
 
 app.post(
@@ -65,7 +64,6 @@
   async (req, res) => {
     const signature = req.headers["x-request-network-signature"] as string;
     const deliveryId = req.headers["x-request-network-delivery"] as string;
-    const isTest = req.headers["x-request-network-test"] === "true";
 
     if (!signature || !deliveryId) {
       return res.status(400).send("missing headers");
@@ -86,39 +84,26 @@
       return res.status(401).send("invalid signature");
     }
 
-    // 2. Idempotency: dedupe on delivery ID
-    const claim = await redis.set(
-      `webhook:${deliveryId}`,
-      "1",
-      "EX",
-      86400, // 24h
-      "NX",
-    );
-    if (!claim && !isTest) {
-      return res.status(200).send("duplicate, ignored");
-    }
-
-    // 3. Parse and route
+    // 2. Parse and route. Each business operation uses deliveryId as an
+    // idempotency key in its own durable store.
     const event = JSON.parse(req.body.toString("utf8"));
 
     try {
-      await handleEvent(event);
+      await handleEvent(event, deliveryId);
+      return res.status(200).send("ok");
     } catch (err) {
-      // Return non-2xx to trigger retry (1s, 5s, 15s — up to 3 retries)
       console.error("handler failed", err);
       return res.status(500).send("handler error");
     }
-
-    res.status(200).send("ok");
   },
 );
 
-async function handleEvent(event: any) {
+async function handleEvent(event: any, deliveryId: string) {
   switch (event.event) {
     case "payment.confirmed":
     case "payment.confirmed.client_id":
     case "payment.confirmed.checkout":
-      await markOrderPaid(event.requestId, event.txHash);
+      await markOrderPaid(event.requestId, event.txHash, deliveryId);
       break;
 
     case "payment.partial":
@@ -128,32 +113,46 @@
         event.requestId,
         event.amount,
         event.totalAmountPaid,
+        deliveryId,
       );
       break;
 
     case "payment.failed":
-      await flagFailedPayment(event.requestId);
+      await flagFailedPayment(event.requestId, deliveryId);
       break;
 
     case "request.recurring":
-      await onRecurringInvoice(event.originalRequestId, event.requestId);
+      await onRecurringInvoice(event.originalRequestId, event.requestId, deliveryId);
       break;
 
     case "compliance.updated":
-      await syncKycStatus(event.clientUserId, event.kycStatus);
+      await syncKycStatus(event.clientUserId, event.kycStatus, deliveryId);
+      break;
+
+    // Payer-funnel telemetry from the Secure Payment Page. Never reconcile
+    // money off this — a payer can approve in their wallet and still have the
+    // transaction fail on-chain. Wait for payment.confirmed for settlement.
+    case "secure_payment.user_event":
+      await recordFunnelStep(
+        event.securePaymentToken,
+        event.userEvent,
+        deliveryId,
+      );
       break;
 
     // ... others
   }
 }
 ```
 
+Webhook delivery is at least once, not exactly once. Each business operation must atomically record the delivery ID with the state it changes, then make a repeat delivery a successful no-op. If an operation calls another service, pass the delivery ID as that service's idempotency key too. A process can fail after a side effect but before it returns `200`.
+
 ## Headers reference
 
 | Header | Description |
 | --- | --- |
 | `x-request-network-signature` | HMAC-SHA256 of the raw JSON body, hex-encoded |
 | `x-request-network-delivery` | ULID — use as idempotency key |
 | `x-request-network-retry-count` | `0`–`3`, current retry attempt |
 | `x-request-network-test` | `true` only for `/v1/webhook/test` deliveries |
 
@@ -170,22 +169,42 @@
 
 ## Common patterns
 
 ### Idempotency
 
-The same `payment.confirmed` event might arrive twice (network blip, retry overlap). Dedupe on `x-request-network-delivery`.
-
-### Routing by Client ID
+The same `payment.confirmed` event might arrive twice (network blip, retry overlap). Use `x-request-network-delivery` as the idempotency key. Record it atomically with the business update in your durable store; do not use a check-then-act cache lookup, because overlapping deliveries can both pass the check.
 
-If your platform has many merchants, give each their own Client ID. The webhook payload includes `clientId` so you can route events to the right tenant.
+For a local database update, add a `webhook_deliveries` table with a unique `delivery_id` column, then insert that ID in the same transaction as the business update:
 
 ```typescript
-async function markOrderPaid(requestId: string, txHash: string) {
-  const order = await db.orders.findOne({ where: { requestId } });
-  if (!order) return; // not ours
-  await db.orders.update({ where: { id: order.id }, data: { paidAt: new Date(), txHash } });
+async function markOrderPaid(
+  requestId: string,
+  txHash: string,
+  deliveryId: string,
+) {
+  await db.transaction(async (tx) => {
+    const order = await tx.orders.findOne({ where: { requestId } });
+    if (!order) return; // not ours
+
+    const claim = await tx.execute(
+      `INSERT INTO webhook_deliveries (delivery_id)
+       VALUES ($1)
+       ON CONFLICT (delivery_id) DO NOTHING`,
+      [deliveryId],
+    );
+    if (claim.rowCount === 0) return; // already applied
+
+    await tx.orders.update({
+      where: { id: order.id },
+      data: { paidAt: new Date(), txHash },
+    });
+  });
 }
 ```
 
+### Routing by Client ID
+
+If your platform has many merchants, give each their own Client ID. The webhook payload includes `clientId` so you can route events to the right tenant.
+
 ### Slack alerts on failure
 
 ```typescript
@@ -201,7 +220,7 @@
 
 ### Crypto-to-fiat status tracking
 
 The `payment.processing` event includes a `subStatus` field that progresses through `initiated → pending_internal_assessment → ongoing_checks → sending_fiat → fiat_sent`. Surface this in your UI so the payee sees real-time offramp progress.
 
 ## Local development