Rotate a webhook signing secret

Rotate an endpoint's signing secret if it may have leaked, or as part of your regular key changes. BillPro issues a new secret and stops using the old one straight away. The endpoint keeps its URL, events, status and delivery log.

Before you start

• An Admin user with API Access turned on.
• A way to update the secret on your server quickly, such as an environment variable or a secrets manager.

How rotation affects deliveries

Between the rotation and your server update, your endpoint rejects requests with 401. BillPro treats these as failed attempts and retries them, signed with the new secret. Once your server has the new secret, the retries succeed.

A request that was already on its way when you rotated is signed with the old secret. If it arrives after your update, it fails your check. BillPro retries it with the new secret.

To keep the gap short, have the secret update ready before you rotate. Rotate at a quiet time if you can.

Rotate the secret

1. From the user icon menu, select Webhooks.

2. Click the endpoint URL.

3. In Signing secret, click Rotate.

4. In Issue a new signing secret?, click Rotate.

5. On the New Signing Secret Issued screen, click the copy button beside the new secret.

6. Update the secret on your server and deploy the change.

7. Click Go to the endpoint.

8. In Recent deliveries, click Send test event. Check that it shows Succeeded.

9. Check for deliveries that show Failed since the rotation, and click Send again on each one.

BillPro records every rotation and reveal with your user, the time, your IP address and the page you used. It never records the secret itself.

If several endpoints share your server

Each endpoint has its own secret. Rotating one doesn't change the others. If your server receives from several endpoints, give each endpoint its own URL path. Then check each request with the secret for that path.