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

# Events

Event lifecycle — received, processing, delivered, and failed states.

Every webhook hookstream receives becomes an event — an immutable record of the HTTP request with its own lifecycle, storage strategy, and retry semantics.

## What is an Event?

An event represents a single webhook request captured by a source. Each event stores the complete HTTP request: method, headers, body, query parameters, source IP, and content type — plus a unique ID and timestamp. Events are immutable; retries create new delivery attempts but never mutate the original event.

## Event Lifecycle

Events move through four states:

1. **`received`** — webhook captured and stored in D1.
2. **`processing`** — running through the pipeline (filter → transform → deliver).
3. **`delivered`** — successfully delivered to every matched destination.
4. **`failed`** — delivery failed after all retries were exhausted.

Events with no matching connections stay in the `received` state indefinitely. That's not a bug — it just means nothing was routed to process them yet. You can wire up a connection later and replay them.

## Storage

hookstream picks storage based on payload size:

- **Inline in D1** for bodies under 10KB — fast, cheap, and queryable.
- **R2 object storage** for larger payloads, with the R2 key referenced in D1.
- **Metadata in D1 always** — headers, method, query params, and timestamps.

Events older than 30 days are archived to R2 as NDJSON, partitioned by org and date. Your dashboard queries stay fast and you still have access to the historical record when you need it.

Free plans retain events for 7 days, Pro for 30 days, and Enterprise for 90 days. Archived events remain accessible via R2 even after they age out of D1.

## Searching & Filtering

The Events API and dashboard both support:

- **Source filter** — show events from a specific source
- **Status filter** — `received`, `delivered`, `failed`
- **Time range** — filter by start and end timestamp
- **Search** — full-text search across event bodies
- **Cursor pagination** — efficient forward/backward traversal

## Retrying Events

Failed events can be retried individually or in bulk:

- **Individual** — `POST /v1/events/:id/retry` re-runs a single event through the pipeline.
- **Bulk** — `POST /v1/issues/:id/retry` retries every event tied to an issue.

Retries always create new delivery attempts while preserving the original event. You can retry the same event as many times as you want without losing the original record or the audit trail.

## Next Steps

**[Events API](/api/events)**

List, search, and retry events programmatically.
  **[Delivery Attempts API](/api/delivery-attempts)**

Per-attempt records with status codes and latencies.
  **[Event Replay Guide](/guides/event-replay)**

Replay historical events against new destinations.
  **[Delivery Pipeline](/concepts/delivery-pipeline)**

How events move from ingestion to delivery.