> For the complete documentation index, see [llms.txt](https://api-docs.urbanpiper.com/downstream/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.urbanpiper.com/downstream/resources/webhook-circuit-breaker.md).

# Webhook Circuit Breaker

Failed webhook deliveries are retried (see Setting-up Webhooks). To keep our infrastructure stable and to stop sending calls to endpoints that are down for a long time, we use a *Webhook Circuit Breaker* (WCB).

For the communication of an external system and ours, we have kept a **Connection timeout of 3 seconds** and **Read timeout of 5 seconds**. It is expected that any third party listening to our webhooks data is responded back within this time window.

The circuit breaker counts failures per business and per webhook host. Only connection timeouts, read timeouts and connection or SSL errors count as failures. HTTP error responses (for example `500` or `400`) are retried, but they don't count toward the circuit breaker. When one business has more than 15 such failures to the same host within a minute, the circuit breaker *trips*: all of that business's active webhooks on that host are disabled (for example order relay, order status and store action webhooks). The breaker works per business: another business's webhooks on the same host are only disabled when that business also goes over the limit. If the host is down for everyone, each business trips separately, so in practice they usually all get disabled within a minute.

When the WCB is tripped, no webhook payloads will be pushed to the particular 3rd party URLs. If even a single webhook callback URL (*say Rider Status Update*) associated with the 3rd party breaches the throttle, then other webhook callbacks associated with the same hostname will also be disabled. Our system checks from which domain/hostname we are receiving the failures and when the failure rate is breached, our system automatically disables all the webhook endpoints associated with that same domain URL.

The webhooks are re-enabled automatically. They stay disabled for 1 minute if the circuit breaker has tripped fewer than 5 times in the past 7 days for your POS (all your businesses together), and for 3 minutes if it has tripped 5 or more times.

For the orders which were not relayed in the timeframe of webhook deactivation, our system tries to push them at once when the webhooks are re-enabled. When we try to re-push the data and at that time if the third-party system is not responding again, the WCB will get triggered again.

When the circuit breaker trips, an email is sent to the POS partner's contact email(s) on file with UrbanPiper and to the business's primary contact email(s). To add or change these addresses, contact your UrbanPiper PoC.

The email alert will provide you with the details of:

* short information about WCB
* which business was impacted
* which all URLs got disabled
* Count of WCB tripped in last 7 days
* Status code

The email alert notification will have a subject - *Webhooks disabled: {{**biz\_name**}}*.

**Note:** When the webhooks are enabled our system try to push the unsent orders at once to your URLs. In this event, whatever the state of the order present in the Urbanpiper system, the same will be present in the Order Relay payload under the state/order\_state attribute.\
\
For example - At the time of order push in retry attempt, if the state of the order is Acknowledged in our system due to status change happening from aggregator, then in the order relay payload, the state/order\_state attribute will have the *Acknowledged* status instead of *Placed*. Please make sure that you do not expect only a Placed state value to be passed in that attribute.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://api-docs.urbanpiper.com/downstream/resources/webhook-circuit-breaker.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.