> ## Documentation Index
> Fetch the complete documentation index at: https://requestnetwork-08-31-chore-document-current-webhook-delivery.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks & Events

> Real-time notifications for Secure Payment, KYT screening, and hosted onboarding events.

## Overview

Webhooks notify your server when Request Network processes a Secure Payment, completes KYT screening, or finishes hosted onboarding. The [Webhooks reference](/api-reference/webhooks) is the canonical guide for endpoint setup, recipients, and payloads.

## Event categories

Current Secure Payment and orchestrator integrations use these events:

| Category                   | Events                                                                                        |
| -------------------------- | --------------------------------------------------------------------------------------------- |
| **Payment**                | `payment.confirmed`, `payment.failed`                                                         |
| **KYT screening**          | `kyt.screening.completed`                                                                     |
| **Secure Payment Page**    | `secure_payment.user_event`                                                                   |
| **Payer-wallet allowlist** | `secure_payment.access_rejected`                                                              |
| **Hosted onboarding**      | `client_id.linked` — a platform completes onboarding to link its Client ID to an orchestrator |

The platform's Client ID and a linked orchestrator do not receive the same events. See the [current webhook event catalog](/api-reference/webhooks#current-webhook-events) for the recipient of each event and its authentication.

### Legacy integrations

`payment.partial`, `payment.refunded`, `payment.processing`, `compliance.updated`, `payment_detail.updated`, and `request.recurring` remain available for existing API integrations. They do not apply to current Dashboard, Secure Payment Page, or orchestrator workflows. See [Legacy integrations](/api-reference/webhooks#legacy-integrations).

<Note>
  Payment payloads include `payerAddress`, the address used to make the payment, and `payerEoaAddress`, the payer's connected wallet address. These can differ when a smart account is used. Both are `null` when unavailable. Payloads from Secure Payments created with a Client ID include `clientId`; orchestrated payments also include `orchestratorId`.
</Note>

For full payload schemas and headers, see the [Webhooks reference](/api-reference/webhooks).

## How It Works

```mermaid theme={null}
graph LR
    A[Event Occurs] --> B[HMAC Signed POST]
    B --> C[Your Endpoint]
    C --> D[Verify & Process]
    D --> E[Return 200 OK]
```

**Process:**

1. **Event occurs:** Payment confirmed, KYT screening completes, or hosted onboarding finishes
2. **Secure delivery:** HMAC SHA-256 signed POST to your configured endpoint
3. **Your processing:** Verify `x-request-network-signature`, update application state
4. **Reliable delivery:** 3 retries (1s, 5s, 15s delays) with 5-second timeout

## 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

* **HMAC SHA-256 signatures:** Every webhook includes `x-request-network-signature` header
* **HTTPS required:** Production endpoints must use secure connections
* **Test webhook identification:** `x-request-network-test` header for development

### Development Tools

* **Test deliveries:** Use the relevant platform or orchestrator test endpoint. See the [Webhooks reference](/api-reference/webhooks).
* **ngrok integration:** Receive webhooks locally during development
* **Comprehensive logging:** Request API logs all delivery failures with attempt details

## Common Use Cases

* **Invoice systems:** Automatically mark invoices as paid when `payment.confirmed` received
* **Order fulfillment:** Release goods or services immediately after payment confirmation
* **Failed-payment handling:** Respond to `payment.failed` when payment execution fails
* **KYT workflows:** Respond to approved or rejected `kyt.screening.completed` results
* **User-event visibility:** Track wallet connection and signature progress on the Secure Payment Page via `secure_payment.user_event`
* **Payer-wallet monitoring:** Detect attempts by wallets that are not allowed to pay via `secure_payment.access_rejected`
* **Hosted onboarding:** Complete a platform's onboarding to your orchestrator after `client_id.linked`

## Implementation

<CardGroup cols={2}>
  <Card title="Webhook Reference" href="/api-reference/webhooks">
    Complete technical documentation with setup, payloads, and code examples
  </Card>

  <Card title="Implementation Examples" href="/api-reference/webhooks">
    Working webhook handlers with Express.js and Next.js
  </Card>

  <Card title="Auth API webhook endpoints" href="https://auth.request.network/open-api/#tag/webhook" icon="webhook">
    POST /v1/webhook to create, GET/PUT/DELETE to manage, /test to fire test deliveries
  </Card>
</CardGroup>