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 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

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}}'

{ "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 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.