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

# Webhook Recovery

> Operational runbook for missed, delayed, duplicate, or compact webhook payloads.

## Recovery Flow

```mermaid theme={null}
flowchart LR
    A["Expected event missing or rejected"] --> B["Fetch canonical transaction state"]
    B --> C["List webhook events"]
    C --> D["Inspect event telemetry"]
    D --> E{"Need redelivery?"}
    E -- "Yes" --> F["Replay event"]
    E -- "No" --> G["Continue reconciliation"]
    F --> H["Confirm delivery result"]
    H --> G
```

## When to Run Recovery

* Missing expected event within your SLA.
* Signature verification failures due to deployment/config changes.
* Suspected delivery disruptions.
* Compact payload received with truncated payload indicator.

## Recovery Steps

1. Query your local event store by `merchant_reference` or `transaction_id`.
2. Fetch latest transaction state via `GET /transactions/{id}` or `GET /transactions/reference/{merchant_reference}`.
3. Inspect local webhook log state with `GET /webhooks/events`.
4. Inspect per-event delivery telemetry with `GET /webhooks/events/{event_id}`.
5. Replay a known event with `POST /webhooks/events/{event_id}/replay` when redelivery is required.
6. Reconcile final status and revenue via transaction and revenue endpoints.

## Compact Payload Handling

If you receive a compact payload marker (`compact_payload` / `payload_truncated`):

1. Treat event as valid envelope notification.
2. Fetch canonical transaction status from read endpoints.
3. Continue normal reconciliation path.

## Replay Guidance

* Replay only when your consumer missed or rejected a previously emitted event.
* Replayed events preserve the original webhook `id`, so your dedupe logic must still treat them as the same logical event.
* After replay, confirm progress with `GET /webhooks/events/{event_id}`.

## Recommended Partner Runbook

* Start with `GET /transactions/{id}` or `GET /transactions/reference/{merchant_reference}` when business state matters more than delivery state.
* Use `GET /webhooks/events` to find the relevant event if you know the transaction or reference but not the webhook `id`.
* Use `GET /webhooks/events/{event_id}` before replay so you can confirm whether the delivery issue is still active.
* Replay only the specific missed event you need; do not treat replay as a substitute for periodic reconciliation.

## Duplicate Handling

* Use webhook `id` as your dedupe key.
* Reprocessing the same event must be safe and no-op.