iOS 16 and iOS 17 support ends late July 2026. Update your device to iOS 18.0 or later to continue receiving Cerby app updates.
Ctrlk
CerbyDeveloper PortalSupportWeMakeCerby
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Rotate a webhook signing key

This article describes how to rotate a webhook signing key in Cerby when a key is compromised or as part of a regular key rotation policy.

Who can use this feature?

  • Workspace Owners, Super Admins, and Admins

  • Supported using the Cerby web app

As a workspace Owner, Super Admin, or Admin, you can rotate a webhook's signing key when a key is compromised or as part of a regular key rotation policy. During rotation, Cerby dual-signs requests with both the old and new keys for 24 hours, giving your system time to update its stored key before the old key expires. You cannot start a second rotation while a grace period is active.

During the 24-hour grace period, each delivery includes two X-Cerby-Signature headers and two X-Cerby-Signature-Key-Id headers, with the new key first. Accept the request if either signature validates.

To rotate a signing key, complete the following steps:

  1. Log in to your Cerby workspace.

  2. Select Settings from the left navigation. The Workspace Configuration page is displayed.

  3. Select the Webhooks left tab.

  4. Click the name of the webhook whose key you want to rotate. The webhook detail page is displayed.

  5. Locate the Signing and verification card and click the rotate button:

    • Ed25519: Click Rotate public key.

    • HMAC-SHA256: Click Rotate secret.

    A confirmation dialog box is displayed, describing the 24-hour dual-sign grace period.

  6. Review the confirmation and click the confirm button:

    • Ed25519: Click Rotate public key.

    • HMAC-SHA256: Click Rotate secret.

    For Ed25519, the rotation begins immediately. The new public key appears in the Signing and verification card.

    For HMAC-SHA256, a dialog box is displayed showing the new signing secret.

HMAC-SHA256 only: Copy the new Signing secret value before closing the dialog box. Cerby displays it only once and cannot recover it.

  1. Update your stored key in your verification system.

  2. Click the Done button. Cerby begins dual-signing requests with both the old and new keys. After 24 hours, Cerby automatically expires the old key.

Now you are done.

Related articles

Developer reference:

Troubleshooting:

Last updated

Was this helpful?