Circuit Breaker
Understand circuit breaker states, thresholds, and reset behavior.
Every HTTP destination has a per-destination circuit breaker managed by its DeliveryScheduler Durable Object. When an endpoint starts failing hard, the breaker trips and pauses deliveries so hookstream doesn't turn a bad day into a worse one.
The three states
Deliveries flow through as usual. The DO counts consecutive failures. A single success resets the counter.
After 5 consecutive failures the breaker opens. New deliveries are queued (not dropped) and a cooldown alarm is scheduled for 60 seconds out.
When the cooldown alarm fires, the DO releases a single probe delivery. If it succeeds, the breaker closes and any queued events flush in order. If it fails, the breaker returns to open and the cooldown restarts.
Default thresholds
| Setting | Value |
|---|---|
| Failure threshold | 5 consecutive failures |
| Cooldown period | 60 seconds |
| Success threshold | 1 successful probe |
These are per-destination and enforced by the DeliveryScheduler DO.
Monitor the breaker
The circuit breaker surfaces in a few places so you notice when it trips:
- Dashboard — the destination detail page shows
closed,open, orhalf-openlive. - API —
GET https://hookstream.io/v1/destinations/:id/circuitreturns state, failure count, and the last transition timestamp. - Issues — an issue is auto-created when the breaker opens, so it shows up on your Issues page.
- Alerts — the
issue_openedalert type fires on the same event. See Monitoring & Alerts.
Pair the breaker with a notification channel so you find out before customers do.
What happens to queued events
When the breaker is open, new deliveries are stored in the DO's queue. Once it closes — via a successful probe or a manual reset — the queued events drain in order. Events are never dropped here. But if an event sits queued long enough to blow past its retry window, it still moves to the DLQ.
Manually reset a breaker
Fix the underlying problem
Whatever was returning 500s — fix that first. A reset without a fix just re-trips the breaker.
Reset from the dashboard or API
Click Reset circuit on the destination detail page, or call:
bashcurl -X POST https://hookstream.io/v1/destinations/dest_xyz/circuit/reset \ -H "X-API-Key: $HOOKSTREAM_API_KEY"
This closes the breaker immediately, zeroes the failure counter, and flushes queued events.
Watch the next delivery
The next event delivered will either succeed (you're done) or re-open the breaker within a few failures (back to step 1).
Resetting a breaker while the destination is still failing just wastes retry attempts. If you're not sure it's recovered, wait for the 60-second probe to do its job automatically.