Rotate the signing secret

Makes a new signing secret, shown this once. For 24 hours each delivery is signed with both, so you can switch without missing one.

Needs a key with the webhooks:manage scope. Keys and scopes

Send an Idempotency-Key so a retry never acts twice. Idempotency

Path parameters

• idstringrequired

  The webhook’s id.

  Starts with wh_.

Headers

• Idempotency-Keystring

  Any string of up to 255 characters, new for each request. A retry with the same key gets the first answer back for 24 hours, with Idempotent-Replayed: true.

  Up to 255 characters.

Example

curl -X POST "https://usebluebot.com/api/v1/webhooks/wh_1Hq2LxW9cVbN3mKpRtYs0a/rotate-secret" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY" \
  -H "Idempotency-Key: 0f6d8c2e-5b1a-4c7e-9d3f-2a8b6e1c4d70"

Response

200: The webhook, with its new secret.

• idstringrequired

  A wh_ id.

  Starts with wh_.

• object"webhook"required
• urlstringrequired
• descriptionstring or nullrequired
• eventsarray of stringsrequired

  The event types it receives. For a webhook made with ["*"], every type there is now.

  One of message.queued, message.sent, message.delivered, message.read, message.failed, message.unconfirmed, message.expired, message.canceled, message.received, message.edited, message.unsent, reaction.added, reaction.removed, chat.created, contact.created, contact.stopped, contact.unstopped, sequence.completed, broadcast.completed, automation.matched, device.online, device.offline, device.check_failed.

• all_eventsbooleanrequired

  True when it was made with ["*"]: it also receives event types BlueBot adds later.

• api_versionstringrequired

  The payload version it was made with and keeps.

• statusstringrequired

  active; failing while deliveries fail (retried for about 3 days); paused by you, or after 72 hours with no successful answer.

  One of active, failing, paused.

• paused_attimestamp or nullrequired

  When it was paused.

• pause_reasonstring or nullrequired

  Who paused it: failing (72 hours of failures), customer or staff.

  One of failing, customer, staff.

• failing_sincetimestamp or nullrequired

  The first failure since the last success.

• last_success_attimestamp or nullrequired

  The last delivery answered with a 2xx.

• last_failure_attimestamp or nullrequired

  The last delivery that failed.

• last_statusinteger or nullrequired

  The HTTP status of the last answer.

• previous_secret_expires_attimestamp or nullrequired

  After a rotation, when the old secret stops signing alongside the new one.

• created_attimestamprequired

  When it was made.

• secretstringrequired

  The signing secret, whsec_ and base64. Verify webhook-signature with it. Shown when the webhook is made and when the secret is rotated.

{
  "id": "wh_1Hq2LxW9cVbN3mKpRtYs0a",
  "object": "webhook",
  "url": "https://hooks.zapier.com/hooks/standard/1234567/abcdef/",
  "description": "New replies to my CRM",
  "events": [
    "message.received",
    "message.failed"
  ],
  "all_events": false,
  "api_version": "2026-11-13",
  "status": "active",
  "paused_at": null,
  "pause_reason": null,
  "failing_since": null,
  "last_success_at": "2026-11-13T19:44:13.000Z",
  "last_failure_at": null,
  "last_status": 200,
  "previous_secret_expires_at": "2026-11-14T19:41:00.000Z",
  "created_at": "2026-11-01T15:10:00.000Z",
  "secret": "whsec_Zx1q4V8nT2mL6cR0bW9kHs3dPfA7yJuE"
}

Errors

Every refusal has the same envelope and a page of its own. These are the ones this operation can give.

Try it