Circuit Breaker

The circuit breaker automatically stops delivering to a webhook that is consistently failing, preventing wasted retries and giving the downstream service time to recover.

How it works

When enabled on a webhook, the circuit breaker tracks consecutive delivery failures. Once failures reach the configured threshold, the circuit opens and all subsequent deliveries are blocked for a cooldown period. After the cooldown, the circuit enters a half-open state where a single test delivery is attempted. If it succeeds, the circuit closes and normal delivery resumes. If it fails, the circuit opens again.

CLOSEDnormal delivery

──▶

OPENdelivery blocked

──▶

HALF_OPENtest delivery

──▶

CLOSEDif test succeeds

Circuit states

State	Behavior
CLOSED	Normal operation. Deliveries are processed as usual. Failure counter increments on each failure and resets on success.
OPEN	Delivery is blocked. Incoming events are queued but not delivered. The circuit stays open for the configured cooldown period.
HALF_OPEN	After cooldown expires, one test delivery is attempted. Success closes the circuit; failure reopens it.

ℹEvents received while the circuit is OPEN are queued, not discarded. Once the circuit closes again, queued events are delivered in order.

Configuration

Configure the circuit breaker in the webhook settings or via the API.

Field	Type	Default	Description
circuitBreaker.enabled	boolean	false	Enable or disable the circuit breaker
circuitBreaker.threshold	number	5	Number of consecutive failures before the circuit opens
circuitBreaker.cooldownSeconds	number	60	Seconds to wait in OPEN state before testing with a HALF_OPEN delivery

Enable via API

PATCH /api/webhooks/:id

jsonRequest body

{
  "circuitBreaker": {
    "enabled": true,
    "threshold": 10,
    "cooldownSeconds": 120
  }
}

Checking circuit state

GET /api/webhooks/:id

The webhook response includes the current circuit breaker state:

jsonResponse (partial)

{
  "_id": "664a1f2e8b1c4a001f2d0001",
  "name": "Payment processor",
  "circuitBreaker": {
    "enabled": true,
    "threshold": 10,
    "cooldownSeconds": 120,
    "state": "CLOSED",
    "failureCount": 2,
    "lastFailureAt": "2025-05-19T14:30:00.000Z",
    "openedAt": null
  }
}

Best practices

Payment webhooks: Low threshold (3-5), short cooldown (30s) — fail fast, recover fast.
Analytics/logging: Higher threshold (15-20), longer cooldown (300s) — tolerate transient errors.
Third-party APIs: Match cooldown to the provider's typical recovery time and rate limit windows.