Events

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