Trigger rotations with webhooks

Every rotation exposes an incoming webhook: a unique URL plus a secret key that lets external systems — CI pipelines, schedulers, incident tooling — trigger actions on the rotation without going through Slack. In this guide you find your rotation’s webhook URL and key, then call it to rotate duty, set a specific user on duty, or open a mention.

Find your webhook URL and key

1. Open the dashboard at app.roundrobinbot.eu and go to your rotation’s details page.
2. Open the Configure menu in the toolbar and choose Webhooks.
3. Copy the Rotation Webhook URL and the Secret API Key. The key is hidden by default; use the eye button to reveal it or the copy button to copy it directly.

The webhook is created automatically the first time you open this page, and the same URL and key are shown on every later visit.

Note

Only users with edit permission on the rotation can view the webhook key, and the rotation must be enabled. Webhooks are not available for externally managed rotations (for example, rotations synced from PagerDuty or Opsgenie).

Call the webhook

Send an HTTP POST to the webhook URL, replacing ACTION with one of the actions below. Authenticate with the secret key in a webhook-key header. If the action takes parameters, pass them in the query string.

curl -i -X POST \
  -H "webhook-key: YOUR_SECRET_KEY" \
  "https://api.roundrobinbot.eu/webhook/YOUR_WEBHOOK_PATH/rotate"

Actions

Action	URL segment	Query parameters	What it does
Rotate	rotate	None	Advances the rotation to the next user on duty.
Set on duty	setonduty	email (required) — the Slack email address of the user to put on duty	Sets an explicit user on duty. The user must be a member of the rotation.
Mention	mention	userId (required) — Slack user ID of the person asking for help; channelId (required) — Slack channel ID where the mention is answered; message (optional) — free-text context	Opens a mention on the rotation, notifying whoever is on duty, exactly as if the bot had been mentioned in Slack. See What are mentions?.

Example — set a specific user on duty:

curl -i -X POST \
  -H "webhook-key: YOUR_SECRET_KEY" \
  "https://api.roundrobinbot.eu/webhook/YOUR_WEBHOOK_PATH/[email protected]"

Errors

Situation	Result
Missing webhook-key header	401 Unauthorized
Wrong secret key	Request rejected as invalid access code
Unknown action in the URL	404 Not Found
Rotation is disabled	Request rejected; enable the rotation first
setonduty with a missing email, an email that matches no Slack user, or a user who is not a rotation member	Request rejected with a validation error explaining the problem

Caution

Treat the webhook key like a password. Anyone who has both the URL and the key can change who is on duty for the rotation.