Skip to main content

Replace a webhook signing secret

Your receiver trusts a delivery because it is signed with the endpoint's signing secret. If that secret may have leaked (pasted into a chat, committed to a repository, left on a laptop that's gone), anyone holding it can send your receiver requests that look like they came from Jaah. Replace it. Do the same on a schedule if your security policy asks for regular rotation.

Who can do this: your organization's Owners and Admins, on a plan that includes webhooks.

Before you start​

Jaah shows a secret only once, so have your receiver's secret store open, ready to take the new value, before you rotate. For 24 hours after a rotation each delivery is signed with both the old and the new secret, which is what lets you switch without losing a delivery. How a receiver checks the signature is in Verify the signature.

Rotate the secret​

  1. Open Settings, select Integrations, then Webhooks.

  2. Select the endpoint's name, then the Secret tab. Rotated shows when the secret last changed, or Never.

  3. Select Rotate. In Rotate secret?, select Rotate to confirm.

  4. The new secret appears once, in a dialog titled with the endpoint's name and signing secret. Select Copy secret, put it in your receiver's secret store, then select Done. Jaah never shows it again; if you close the dialog without copying it, rotate again.

  5. Switch your receiver to the new secret.

    • After a leak: make the receiver accept only signatures made with the new secret, and drop the old one now. Deliveries still carry an old-secret signature for 24 hours, so a receiver that keeps the old secret also keeps accepting requests forged with it.
    • On a schedule: you have 24 hours. Until then a receiver holding either secret accepts each delivery.
  6. Select Send test. Jaah sends a ping event at once and opens Deliveries, where its row shows Delivered once your receiver accepts it with the new secret. If it shows Failed, hover the status for why, and check the receiver picked up the new value.

  7. Back on Secret, check Rotated shows today's date.

The rotation is recorded in Audit with who did it and when, if your security team asks.

If a delivery failed during the switch​

A delivery your receiver refused while it held the wrong secret shows Failed or Retrying on Deliveries. Select Redeliver on its row: Jaah sends it again with a fresh signature made with the current secret. See Fix a failing webhook.