Failover Destinations

Failover destinations are backup endpoints that automatically receive webhook deliveries when the primary destination fails. This ensures critical webhooks are never lost, even during outages.

How It Works

1. A delivery attempt to the primary destination fails
2. The system retries according to the retry policy (exponential backoff)
3. After failoverAfterAttempts consecutive failures, the delivery is automatically re-routed to failover destinations
4. Failover destinations receive the same payload with an added X-Hookbase-Failover: true header

Configuration

Add failover destinations to a route:

curl -X PATCH https://api.hookbase.app/api/routes/rte_abc123 \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "failoverDestinationIds": ["dst_backup1", "dst_backup2"],
    "failoverAfterAttempts": 3
  }'

Fields

Field	Type	Default	Description
failoverDestinationIds	string[]	[]	Backup destination IDs (max 3)
failoverAfterAttempts	number	3	Failed attempts before switching to failover (1-10)

Limits

• Maximum 3 failover destinations per route
• Failover destinations must be different from primary destinations
• Failover destinations can have their own retry policies

Failover Behavior

When Failover Activates

Failover activates after the configured number of consecutive failed attempts on the primary destination. A single success resets the failure counter.

Attempt 1: ❌ Failed (500)     → counter: 1
Attempt 2: ❌ Failed (timeout) → counter: 2
Attempt 3: ❌ Failed (503)     → counter: 3 = failoverAfterAttempts
→ Failover activated: delivery sent to backup destinations

Failover Headers

Failover deliveries include additional headers:

Header	Description
X-Hookbase-Failover	true — indicates this is a failover delivery
X-Hookbase-Original-Destination	ID of the primary destination that failed
X-Hookbase-Failure-Reason	Error from the last primary attempt

Failover Retry Policy

Failover destinations use their own retry policy. If a failover destination also fails, the delivery enters the dead letter queue.

Interaction with Circuit Breaker

Failover and circuit breaker work together:

1. Circuit closed — Normal delivery with retries
2. Circuit opens — Failover destinations are activated immediately (no need to wait for failoverAfterAttempts)
3. Circuit half-open — Probe requests go to primary; real traffic continues to failover
4. Circuit closes — Traffic returns to primary destination

Primary ──[fails]──→ Circuit Opens ──→ Failover Active
   ↑                                       │
   └──── Circuit Closes ←── Probes OK ←───┘

TIP

Configure both failover and circuit breaker for maximum reliability. The circuit breaker prevents overloading a struggling destination, while failover ensures deliveries still get through.

Examples

Basic Failover Setup

# Create a backup destination
curl -X POST .../destinations \
  -d '{
    "name": "Backup Webhook Handler",
    "url": "https://backup.yourapp.com/webhooks",
    "retryPolicy": { "maxRetries": 3 }
  }'

# Add failover to an existing route
curl -X PATCH .../routes/rte_main \
  -d '{
    "failoverDestinationIds": ["dst_backup"],
    "failoverAfterAttempts": 3
  }'

Multi-Region Failover

curl -X PATCH .../routes/rte_production \
  -d '{
    "failoverDestinationIds": ["dst_us_west", "dst_eu_west", "dst_ap_southeast"],
    "failoverAfterAttempts": 2
  }'

Handling Failover in Your Application

Check for the failover header to handle failover deliveries appropriately:

app.post('/webhooks', (req, res) => {
  const isFailover = req.headers['x-hookbase-failover'] === 'true';

  if (isFailover) {
    console.log('Received failover delivery');
    console.log('Original destination:', req.headers['x-hookbase-original-destination']);
    console.log('Failure reason:', req.headers['x-hookbase-failure-reason']);
  }

  // Process the webhook normally
  processWebhook(req.body);
  res.status(200).json({ received: true });
});

Related

• Routes API — Configure failover fields
• Circuit Breaker — Automatic failure detection
• Pipeline Architecture — Where failover fits in the flow
• Notification Channels — Get alerted on failover events