> 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/api/endpoints/setting-up-webhooks.md).
# Setting-up Webhooks
API to create/update external system webhook endpoints
This endpoint allows you to create, list, view and update webhooks for a certain set of events.
{% hint style="warning" %}
**Constraints & Expectations**
A *throttle limit* is applicable on this endpoint limiting the maximum number of requests/min to **5**. If you breach this threshold, the platform will respond with a `429` error response code and you will not be able to make new requests for a duration of **1 min**.
{% endhint %}
Sample cURL - POST
```json
curl -X POST \
https://pos-int.urbanpiper.com/external/api/v1/webhooks/ \
-H 'Authorization: apikey ******:******' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache' \
-d '{
"active": true,
"event_type": "rider_status_update",
"retrial_interval_units": "seconds",
"url": "http://example.com/",
"headers": {
"content-type": "application/json",
"x_api_token": "4trgfdsfd243tg54342rewfcef"
}
}'
```
Response
```
{
"status": "success",
"message": "webhooks has been successfully created.",
"webhook_id": 36
}
```
Sample cURL - GET
```
curl -X GET \
https://pos-int.urbanpiper.com/external/api/v1/webhooks/36/ \
-H 'Authorization: apikey ******:******' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache'
```
Response
```
{
"active": true,
"event_type": "rider_status_update",
"headers": {
"content-type": "application/json",
"x_api_token": "4trgfdsfd243tg54342rewfcef"
},
"retrial_interval_units": "seconds",
"url": "http://example.com/",
"webhook_id": 36
}
```
**Request URL**
**POST** `/external/api/v1/webhooks/`\
— creates a webhook
**GET** `/external/api/v1/webhooks/`\
— returns a list of configured webhooks
**GET** `/external/api/v1/webhooks/{webhook_id}/`\
— returns a particular webhook
**PUT** `/external/api/v1/webhooks/{webhook_id}/`\
— updates a webhook
**Request header**
| Parameter | Value |
| :---------------------------------------------: | ------------------------------------------------ |
| `Authorization` | API key based auth header. Refer authentication. |
**Request Parameters**
| Parameter | Type | Value |
| :------------------------------------------: | ------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `active` | boolean | webhook is currently active or not. |
| `event_type` | string | event type to which you are subscribing to. Supported events are :
order\_placed: order placed event.
order\_status\_update: order state change event.
rider\_status\_update: rider state change event.
inventory\_update: callback url for managing catalogue call.
store\_creation: callback url for store creation call.
store\_action: event for callback url for Store Actions API call.
item\_state\_toggle: event for callback url for items actions done through Item/Option - actions API call.
catalogue\_timing\_grp: event for callback url for Category Timing Groups API.
option\_state\_toggle: event for callback url for option actions done through Item/Option - actions API call.
hub\_menu\_publish: event for callback url for menu publish to aggregators.
order\_items\_oos\_processed: event for callback url for mark order item out-of-stock.
|
| `headers` | object | custom headers to be included while posting the event body. |
| `retrial_interval_units` | string | unit based on which retrial is done. allowed values are minutes or seconds (default being minutes). 2^n is the interval in which the retry is done where n being \[0-4], first retry happens in 2^0 - 1 seconds/minutes and second on 2^1 - 4 seconds/minute ... 2^4 - 32 seconds/minutes |
| `url` | string | url to which the event body to be posted. |
| `webhook_id` | string | Unique ID returned during the POST event. This extra parameter is used in `PUT` request to update the specific webhook. |
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://api-docs.urbanpiper.com/downstream/api/endpoints/setting-up-webhooks.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.