Rotate secrets

Each webhook has its own signing secret, whsec_…, shown once when you make it. Rotate it when it may have leaked (pasted into a chat, committed to a repository, known to somebody who left), when you've lost it, or on a schedule your security policy sets.

What rotating does

• BlueBot makes a new secret and shows it only once. The API returns it in its answer, and the dashboard shows it on screen.
• For the next 24 hours, every delivery is signed with both secrets. webhook-signature carries two values, the new secret's first: v1,<new> v1,<old>.
• The webhook's previous_secret_expires_at says when the old secret stops signing. After that, only the new one does.
• Nothing else changes: the address, the events and the deliveries waiting are the same.

Because each delivery carries a signature from each secret during those 24 hours, a handler that knows only the old secret and a handler that knows only the new one both accept it. That's what makes the switch safe: you never need both secrets in your code.

Rotate without missing a delivery

curl -X POST "https://usebluebot.com/api/v1/webhooks/wh_1Hq2LxW9cVbN3mKpRtYs0a/rotate-secret" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY" \
  -H "Idempotency-Key: rotate-wh_1Hq2LxW9cVbN3mKpRtYs0a-2026-11"

{
  "id": "wh_1Hq2LxW9cVbN3mKpRtYs0a",
  "object": "webhook",
  "url": "https://bookings.example.com/bluebot/webhooks",
  "status": "active",
  "previous_secret_expires_at": "2026-11-14T19:41:00.000Z",
  "secret": "whsec_Q2nVb8mLx0RkT4cW9yHj3PdZs6EuAa1F"
}

If the secret leaked

Anybody with the old secret can sign posts your handler accepts for as long as your handler trusts that secret. BlueBot's 24-hour window only decides which secrets BlueBot signs with; your handler decides which it accepts. So after a leak, put the new secret in place as soon as you can. Once your handler verifies with the new secret only, a post signed with the leaked one fails your check, even though BlueBot still adds its own old-secret signature for the rest of the day.

Then look for posts that arrived during the leak and don't match an event BlueBot sent: every genuine event is in the event feed under its id.

Lost the secret?

BlueBot shows a secret once and can't show it again. Rotate to get a new one. If nothing verifies with the old secret any more, the 24-hour window doesn't matter to you, and you can deploy the new secret whenever it's ready; deliveries that fail meanwhile are retried for 72 hours.

Next