> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecadence.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Inbound webhooks

> Start a bot's routines from another system.

Each bot has a webhook URL. When another system sends a `POST` to it, the bot's active routines with **Webhook** turned on run, with the request body as their input. Use it to react to new orders, form submissions, alerts, or anything that can send an HTTP request.

## Set it up

1. Create a [routine](https://docs.usecadence.gg/work/routines.md) on the bot, add the **Webhook** trigger, and switch it **Active**.
2. The routine editor shows the URL to **POST to** and a key. Copy both.

Click **Rotate key** to replace the key. The old key stops working at once. From the API, `bots/rotateWebhookSecret` with `{ botId }` returns a new `secret` and the `path`.

## Send an event

```bash theme={null}
curl -s -X POST "$CADENCE_URL/api/v1/bots/YOUR_BOT_ID/webhook" \
  -H "Authorization: Bearer $WEBHOOK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{"event": "order.created", "order": {"id": 1042, "total": 120}}'
```

```json theme={null}
{ "ok": true, "messageId": "...", "runId": "...", "seq": 57 }
```

| Header | Required | Use |
| - | - | - |
| `Authorization: Bearer <key>` | Yes | The webhook key. This is not your sign-in token. |
| `Content-Type` | No | JSON is read as JSON; other bodies are passed as text. |
| `Idempotency-Key` | No | A unique id per event. A repeat with the same key does not run twice. An `id` or `event_id` field in a JSON body works too. |

## Limits and responses

| Status | Meaning |
| - | - |
| `200` | Accepted. The response names the run that started. |
| `401` | Wrong key, or no such bot. Both look the same on purpose. |
| `413` | Body larger than 64 KB. |
| `503` | Temporarily unavailable. Retry later. |

Up to five active webhook routines on the bot run for each event.

## Safety

The webhook body comes from outside, so Cadence treats it as untrusted. A run started by a webhook needs the bot owner's [approval](https://docs.usecadence.gg/work/approvals.md) for any action with side effects, and cannot visit new websites.

## GitHub

For GitHub events, turn on the **Git event** trigger and point a GitHub webhook at `/api/v1/bots/YOUR_BOT_ID/github` with the key as the GitHub webhook secret. Cadence checks GitHub's `X-Hub-Signature-256` signature.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.