Skip to content
Prividium

Rotating Signing Keys

Rotate immediately if a signing key is exposed or suspected compromised.

1. Rotate from the Admin Dashboard

You can rotate signing keys directly from the webhook details page in the admin UI.

  1. Open Webhooks.
  2. Select the webhook row to open its details page.
  3. Select Rotate Signing Key.
  4. Enter retire_after_secs.
    • The field is required in the UI.
    • The default value is 86400.
  5. Select Rotate.
  6. In the confirmation dialog, type Rotate signing key.
  7. Confirm the rotation.
  8. Copy the new signing key from the one-time modal.
  9. Acknowledge the modal to finish the flow.

2. Obtain Endpoint UUID for Direct API Use

Use list endpoints to find endpoint.id for the webhook you want to rotate. Or open the webhook details page in the admin UI and copy the webhook ID.

Address webhook list:

curl "http://localhost:8000/api/v1/address-webhook?limit=20&offset=0" \
  -H "Authorization: Bearer <TOKEN>"

Event webhook list:

curl "http://localhost:8000/api/v1/event-webhook?limit=20&offset=0" \
  -H "Authorization: Bearer <TOKEN>"

Use endpoint.id as <ENDPOINT_UUID>.

3. Rotate Signing Key with the API

Rotate event webhook signing key:

curl -X POST "http://localhost:8000/api/v1/event-webhook/<ENDPOINT_UUID>/signing-keys/rotate" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "retire_after_secs": 86400,
    "version": "v1"
  }'

Rotate address webhook signing key:

curl -X POST "http://localhost:8000/api/v1/address-webhook/<ENDPOINT_UUID>/signing-keys/rotate" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "retire_after_secs": 86400,
    "version": "v1"
  }'

4. Rotation Parameters

Direct API requests currently support these fields:

  • retire_after_secs: overlap window where old and new keys are valid. 86400 seconds is a practical default.
  • version: signature version. Current value is v1.

The admin dashboard exposes only retire_after_secs. It does not let you configure version.

API requests can omit both fields:

{}

5. Rotation Response

The response includes:

  • signing_key
  • key_id
  • version

6. Multi-Signature Overlap

During the rotation overlap window, deliveries can include more than one signature:

webhook-signature: v1,<sig1> v1,<sig2>

Consumers should:

  1. Parse all provided signatures.
  2. Attempt verification with all active keys.
  3. Accept the request if any signature validates.

See Verifying Signatures for the verification details.

  1. Rotate and securely store the new signing key.
  2. Deploy verifier changes to accept both old and new keys.
  3. Wait for the overlap window to pass.
  4. Remove the old key from your verifier.

Common Pitfalls

  • Rotating but not storing the newly returned key.
  • Keeping only one active key in verification during overlap.
  • Removing the old key before retire_after_secs has elapsed.