> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cashweb.cash/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Delivery model and consumption requirements for financial-grade webhook processing.

CashWeb emits webhook events for partner transaction lifecycle and payout milestones.

## Delivery Model

```mermaid theme={null}
sequenceDiagram
    participant CashWeb as "CashWeb"
    participant Partner as "Partner Webhook Endpoint"
    participant PartnerAPI as "Partner Recovery API"

    CashWeb-->>Partner: "POST webhook event"
    alt "Webhook accepted"
        Partner-->>CashWeb: "2xx"
    else "Webhook missed or rejected"
        Partner->>PartnerAPI: "GET /webhooks/events"
        Partner->>PartnerAPI: "GET /webhooks/events/{event_id}"
        Partner->>PartnerAPI: "POST /webhooks/events/{event_id}/replay"
        CashWeb-->>Partner: "Redelivery of same webhook id"
    end
```

## Delivery Guarantees

* At-least-once delivery.
* Duplicate deliveries are possible.
* Ordering is not guaranteed.

Your consumer must be idempotent and order-tolerant.

## Canonical Envelope

Each webhook request body uses:

```json theme={null}
{
  "id": "<event_uuid>",
  "type": "transaction.completed",
  "data": { ... }
}
```

## Processing Pattern

1. Verify signature.
2. Deduplicate by event `id`.
3. Persist raw event for audit.
4. Apply idempotent business update.
5. Return success quickly.

## Delivery Telemetry Endpoint

Use `GET /webhooks/events/{event_id}` for retry diagnostics:

* `delivery_status`
* `attempts`
* `last_error`
* timestamps

This endpoint is for observability, not payload replay.

## Recovery Endpoints

Use these partner-scoped endpoints during incident recovery:

* `GET /webhooks/events`
* `GET /webhooks/events/{event_id}`
* `POST /webhooks/events/{event_id}/replay`

`GET /webhooks/events` returns the partner-scoped webhook event history so you can find events by transaction or time window.
`POST /webhooks/events/{event_id}/replay` schedules a new delivery attempt for the same webhook event and preserves the original webhook `id`.