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

# Event History and Replay

> Inspect webhook deliveries in the dashboard, retry failed events, and use the Events API.

When your endpoint is down or returns non-2xx, deliveries fail. The merchant dashboard records attempts so you can fix the receiver and resend without losing business events.

## Dashboard event log

Open **Settings → API & Webhook → Webhooks**:

`https://merchants.zbx.boomfi.xyz/dashboard/settings/api-keys?tab=webhooks`

<img src="https://mintcdn.com/zbx/dSq06TT4ZbzJ3OV5/webhooks/images/events-log-filters-zbx.png?fit=max&auto=format&n=dSq06TT4ZbzJ3OV5&q=85&s=05c97958e9cb67cbc71c9d553046bfe7" alt="ZBX webhook event history" width="1440" height="900" data-path="webhooks/images/events-log-filters-zbx.png" />

### What you can do

| Capability        | Behaviour                                                                               |
| ----------------- | --------------------------------------------------------------------------------------- |
| List events       | Paginated history for your organisation                                                 |
| Filters           | Event type, action, delivery status (`succeeded` / `failed`), document id, time range   |
| Detail panel      | Payload, delivery status, attempt list (original vs retry), HTTP metadata when captured |
| **Retry**         | Resend one failed event (button disabled unless latest delivery failed)                 |
| **Replay failed** | Queue resend for failed events currently matched on the page                            |

### Retry cooldown

Manual retries enforce a **60 second** cooldown per event. Replaying during cooldown returns rate-limit style errors (HTTP 429) and skips ineligible ids. Queued deliveries poll until attempts complete.

### Permissions

Viewing the log requires the same permission family as managing API keys (`CREATE_VIEW_API_KEY` in the merchant app). Ensure ops engineers hold that permission.

## What a retry does

Manual redispatch POSTs the **stored event document** (exact body already processed for delivery) to your **current** organisation webhook URL, re-signing with your webhook private key and new `X-BoomFi-Timestamp` / `X-BoomFi-Signature` headers. A new delivery attempt row is recorded.

## List events API

```bash theme={null}
curl "https://mapi.zbx.boomfi.xyz/v1/events?event_status=failed&limit=20&page=1" \
  -H "X-API-KEY: sk_test_xxx"
```

Useful query parameters:

| Param              | Purpose                         |
| ------------------ | ------------------------------- |
| `event_status`     | `succeeded` or `failed`         |
| `event_type`       | e.g. Payment                    |
| `event_action`     | e.g. Updated                    |
| `document_id`      | Payment/plan/invoice display id |
| `since` / `until`  | RFC3339 time bounds             |
| `limit` / `page`   | Pagination                      |
| `sort` / `sort_by` | Ordering                        |

List items include delivery snapshot fields such as `delivery_status`, `webhook_url`, `webhook_response_status`, and request header dumps when captured (including signature headers).

## Retry / replay API paths

OpenAPI exposes event detail, single retry, and replay-failed routes under `/events`. Use the dashboard for day-to-day ops, or call those routes programmatically with the same eligibility rules (failed latest delivery, not queued, outside cooldown).

## Operational runbook

1. Alert on failed deliveries or customer reports
2. Open the Webhooks tab filtered to `failed`
3. Inspect response status/body
4. Fix endpoint (downtime, signature bug, 5xx)
5. Retry one event as a smoke test
6. Bulk replay remaining failures
7. Confirm orders updated idempotently

## Related

* [Verify Webhook Signatures](/webhooks/verify-signatures)
* [Webhook Best Practices](/webhooks/best-practices)