The Circuit Breaker Pattern for Third-Party API Integrations: A Practical Guide
Learn how to implement the circuit breaker pattern in third-party API integrations to prevent cascade failures, reduce latency, and build resilient webhook-driven systems.
When a third-party API is unavailable, requests can spend their full timeout waiting for it. Enough waiting requests can consume connections and workers needed by the rest of the application.
A circuit breaker tracks failures and temporarily stops calls to a degraded dependency after a configured threshold is reached. Requests then fail promptly or use a defined fallback.
What a Circuit Breaker Does
The name comes from electrical engineering. An electrical circuit breaker trips when current exceeds a safe level, cutting the circuit to prevent damage. In software, a circuit breaker monitors calls to a dependency and trips when failures exceed a threshold, preventing further calls until the dependency recovers.
A circuit breaker has three states:
Closed (normal operation): requests flow through. The breaker tracks failure rate. If failures stay below the threshold, state stays closed.
Open (tripped): the breaker is tripped. Requests fail immediately without attempting the call. After a configurable timeout, the breaker transitions to half-open to test whether the dependency has recovered.
Half-open: a limited number of test requests are allowed through. If they succeed, the breaker closes. If they fail, it opens again.
In the open state, requests skip the dependency call rather than waiting for its timeout. This reduces waiting work, though the application still needs a safe failure or retry path.
When to Apply This Pattern to Webhook Integrations
Circuit breakers are most valuable in two webhook-related scenarios:
When your webhook handler makes outbound API calls as part of processing. If an order.created webhook triggers a call to a shipping provider's API, and the shipping API is down, every queued order will fail. A circuit breaker around the shipping API call lets your queue back off intelligently rather than burning through retries against a known-down service.
When you are sending webhooks to your customers' endpoints. If a customer's endpoint is returning 500s consistently, continuing to hammer it with retries consumes your delivery infrastructure and backpressure can affect other customers. A per-endpoint circuit breaker pauses delivery to a failing endpoint until it shows signs of recovery.
Implementing a Basic Circuit Breaker
Most languages have mature circuit breaker libraries:
- Node.js:
cockatiel,opossum - Python:
pybreaker - Go:
gobreaker - Java/Kotlin: Resilience4j, Hystrix (legacy)
- Ruby:
circuitbox
A basic implementation with opossum in Node.js:
const CircuitBreaker = require('opossum');
async function callShippingApi(orderId) {
const response = await fetch(
`https://api.shippingprovider.com/orders/${orderId}`,
{ signal: AbortSignal.timeout(5000) }
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
return response.json();
}
const breaker = new CircuitBreaker(callShippingApi, {
timeout: 5000, // call must complete within 5s
errorThresholdPercentage: 50, // open if >50% of calls fail
resetTimeout: 30000, // try again after 30 seconds
volumeThreshold: 5, // need at least 5 calls before evaluating
});
breaker.fallback((orderId) => {
// enqueue for retry, return a placeholder, or throw a known error
return { status: 'pending', message: 'Shipping service unavailable, will retry' };
});
// In your webhook handler:
const result = await breaker.fire(event.data.orderId);The fallback is what runs when the circuit is open. It should handle the degraded case gracefully — enqueueing for retry, returning a safe default, or surfacing a user-appropriate error.
Tuning the Thresholds
The right thresholds depend on your traffic volume and tolerance for false positives.
errorThresholdPercentage: the proportion of recent calls that must fail before tripping. Select this with the minimum request volume and evaluation window; a low threshold can also cause unnecessary outages.
volumeThreshold: the minimum number of calls in the window before evaluating the failure rate. Choose it from traffic volume so a small number of requests does not produce a misleading percentage.
resetTimeout: how long the breaker stays open before probing. Tune it using observed recovery behavior, provider rate limits, and acceptable retry delay. The example’s value is a starting configuration, not a provider recovery guarantee.
Observability for Circuit Breakers
Track breaker behavior so the team can distinguish dependency failures from application errors:
- State transitions (closed → open, open → half-open, half-open → closed) as events with timestamps.
- Failure rate per breaker over time.
- Calls rejected in the open state (these are your fast-fail events — important for understanding impact).
Alert when the open circuit causes unacceptable user impact or exceeds the dependency’s recovery objective. Choose the threshold for the affected workflow.
What the Circuit Breaker Is Not
It is not a substitute for retry logic. Retries and circuit breakers work together: retry for transient failures when the circuit is closed; stop retrying fast and enqueue for later when the circuit is open.
It is not a substitute for a dead-letter queue. Events rejected by an open circuit need to go somewhere. Write them to a queue or table for replay once the circuit closes.