Circuit Breaker

The circuit breaker pattern automatically pauses webhook deliveries to failing destinations, preventing cascading failures and giving struggling services time to recover.

How It Works

The circuit breaker has three states:

State	Description	Behavior
Closed	Normal operation	Deliveries proceed normally
Open	Circuit tripped	Deliveries are paused
Half-Open	Probing for recovery	Limited deliveries to test if destination recovered

State Transitions

┌──────────┐    Failures exceed     ┌──────────┐
│  CLOSED  │ ─────threshold──────► │   OPEN   │
└──────────┘                        └──────────┘
     ▲                                   │
     │                                   │ Cooldown
     │ Probe succeeds                    │ expires
     │                                   ▼
     │                              ┌──────────┐
     └────────────────────────────  │HALF-OPEN │
           Probe successes          └──────────┘
           exceed threshold              │
                                         │ Probe fails
                                         ▼
                                    Back to OPEN

Configuration

Configure the circuit breaker on each route with these parameters:

Parameter	Default	Description
circuitFailureThreshold	5	Consecutive failures before opening
circuitCooldownSeconds	300	Seconds to wait before probing
circuitProbeSuccessThreshold	2	Successful probes needed to close

Via API

# Update circuit breaker configuration
curl -X PATCH "https://api.hookbase.app/api/routes/{routeId}/circuit-config" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "circuitFailureThreshold": 10,
    "circuitCooldownSeconds": 600,
    "circuitProbeSuccessThreshold": 3
  }'

Via Dashboard

1. Navigate to Routes
2. Click the edit icon on a route
3. Expand the Circuit Breaker section
4. Configure the thresholds
5. Click Save Circuit Config

Checking Circuit Status

Via API

# Get circuit breaker status
curl -X GET "https://api.hookbase.app/api/routes/{routeId}/circuit-status" \
  -H "Authorization: Bearer {token}"

Response:

{
  "state": "open",
  "openedAt": "2024-01-15T10:30:00Z",
  "consecutiveFailures": 5,
  "consecutiveSuccesses": 0,
  "config": {
    "failureThreshold": 5,
    "cooldownSeconds": 300,
    "probeSuccessThreshold": 2
  }
}

Via Dashboard

Open circuits display a red Circuit Open badge on the route card. Half-open circuits show a yellow Probing badge.

Manually Resetting the Circuit

If you've fixed the underlying issue and want to immediately resume deliveries:

Via API

# Reset circuit to closed state
curl -X POST "https://api.hookbase.app/api/routes/{routeId}/reset-circuit" \
  -H "Authorization: Bearer {token}"

Via Dashboard

1. Navigate to Routes
2. Find the route with an open circuit (red badge)
3. Click the Reset Circuit button

Notifications

Get alerted when circuits open by linking a notification channel to your route:

# Link notification channel to route with circuit alerts
curl -X POST "https://api.hookbase.app/api/notification-channels/{channelId}/routes" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "routeId": "{routeId}",
    "notifyOnCircuitOpen": true,
    "notifyOnRecovery": true
  }'

Best Practices

1. Set appropriate thresholds: Consider your destination's normal error rate
2. Use with failover: Configure failover destinations for critical routes
3. Monitor alerts: Set up notifications to respond quickly to circuit events
4. Tune cooldown: Longer cooldowns for destinations with slow recovery times

Example Scenarios

High-Volume Route

For routes processing thousands of webhooks per minute:

{
  "circuitFailureThreshold": 20,
  "circuitCooldownSeconds": 120,
  "circuitProbeSuccessThreshold": 5
}

Critical Low-Volume Route

For important routes where every delivery matters:

{
  "circuitFailureThreshold": 3,
  "circuitCooldownSeconds": 60,
  "circuitProbeSuccessThreshold": 2
}

External Third-Party API

For destinations you don't control:

{
  "circuitFailureThreshold": 10,
  "circuitCooldownSeconds": 600,
  "circuitProbeSuccessThreshold": 3
}