In this section · 3 articles

Rotate a destination's signing secret

Replace a destination's signing secret, for example when it may have been exposed, without breaking the receiver: the previous secret keeps signing a second header.

Applies to
Webhook Engine 2.2 and later
Who can do this
Platform owner, Administrator
Permission
feature.webhook.destination.rotate_secret
Where
Webhook Engine › Destinations
On this page

Rotate a secret when it may have been seen by someone it shouldn't have, when a person who knew it leaves, or on a regular schedule your security policy sets.

Before you start

  • You need Rotate Signing Secret (feature.webhook.destination.rotate_secret) and List Destination (feature.webhook.destination.list).
  • Talk to whoever runs the receiving system first. After the rotation, the receiver needs the new secret.

How rotation works

When you rotate, the destination gets a new secret, and the current one becomes the previous secret. From then on, every delivery carries two signatures:

HeaderSigned with
X-Laramin-SignatureThe new secret
X-Laramin-Signature-SecondaryThe previous secret

So a receiver that still has only the previous secret keeps accepting deliveries, as long as it checks the secondary header too. Once it has the new secret, it checks the main header.

The previous secret doesn't expire. It keeps signing the secondary header until you rotate again, when it's replaced by the secret you're retiring. So if a secret was exposed, one rotation isn't enough: rotate again once the receiver has switched to the new secret, and the exposed one stops being sent.

Steps

  1. In the sidebar, open Webhook Engine › Destinations.

  2. Open the destination's row actions menu and select Rotate Secret.

    Webhook Engine › Destinations list with a destination's row actions menu open, showing View, Test Console, Edit and Delete, with Rotate Secret highlighted.
  3. Read Rotate signing secret? and select to confirm.

You see HMAC secret rotated successfully! The old key will remain valid for secondary checks. The Secret Rotated column shows when it happened. Add the column with the columns menu if you don't see it.

Careful: No screen shows the new secret, so you can't hand it to the receiver from the app. See Verify webhook signatures and handle retries before you rotate a secret a receiver depends on.

What happens next

  1. Send a test from the Test Console. Its Request headers tab shows both signature headers. See Test a webhook destination.
  2. Have the receiver's owner switch to the new secret.
  3. If a secret was exposed, rotate once more after the receiver has switched, so the exposed one stops being sent.