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

# Webhooks & Events

> Real-time notifications for payments, transaction screening, and hosted onboarding

## Overview

Webhooks provide real-time notifications when payment, transaction-screening, and hosted-onboarding events occur, enabling immediate response to status changes without constant polling. Depending on the event, Request Network can deliver a notification to a platform's Client ID, its linked orchestrator, or both. See the [Webhooks reference](/api-reference/webhooks#current-webhook-events) for recipient routing and the complete technical contract.

## Event Categories

The current webhook catalog includes these events:

| Category                                    | Events                                         |
| ------------------------------------------- | ---------------------------------------------- |
| **Hosted onboarding**                       | `client_id.linked`                             |
| **Payment**                                 | `payment.confirmed`, `payment.failed`          |
| **Transaction screening**                   | `kyt.screening.completed`                      |
| **Secure Payment Page** (payer funnel)      | `secure_payment.user_event` (with `userEvent`) |
| **Secure Payment** (payer-wallet allowlist) | `secure_payment.access_rejected`               |

For events retained for older API integrations, see [Legacy integrations](/api-reference/webhooks#legacy-integrations).

<Note>
  Payment webhook 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. See the [Webhooks reference](/api-reference/webhooks) for the full payload schema.
</Note>

For delivery headers and currently documented payload examples, 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 completed, or hosted onboarding finished
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
* **Failure handling:** Detect unsuccessful payment attempts with `payment.failed`
* **Payer-funnel 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`

## Implementation

<CardGroup cols={2}>
  <Card title="Webhook Reference" href="/api-reference/webhooks" icon="webhook">
    Endpoint setup, recipient routing, and payloads.
  </Card>

  <Card title="Implementation Examples" href="/use-cases/webhook-reconciliation">
    Working webhook handlers with Express.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>

  <Card title="Orchestrator webhooks" href="/api-reference/webhooks#register-an-orchestrator-webhook" icon="webhook">
    Register and test an endpoint with an `x-orchestrator-key`.
  </Card>
</CardGroup>