Rotate a webhook secret
Webhook secrets authenticate incoming webhook events from Tailscale to your endpoint. You rotate a webhook secret when you need to replace the existing secret with a new one, either as part of regular security maintenance or after a potential compromise. This process generates a new secret while maintaining your webhook endpoint configuration.
Prerequisites
To rotate a webhook secret, ensure you meet the following prerequisites:
- Be an Owner, Admin, Network admin, or IT admin.
- Have an existing webhook endpoint configured in the admin console.
Instructions
The following instructions guide you through the process of rotating a webhook secret in the Tailscale admin console.
Rotating a webhook secret replaces the existing secret with a new one. The old secret stops working immediately after rotation, so you need to update your verification routine with the new secret to continue receiving events.
-
Open the Webhooks page of the admin console.
-
Find the endpoint for which to rotate the secret, then select the
menu > Rotate webhook secret. This opens the Rotate webhook secret modal. -
Select Rotate to confirm you want a new secret.
-
In the Rotate webhook secret modal, select Copy to copy the new secret.
-
Save the secret in a secure location. You won't be able to access it again after closing the modal.
Treat the webhook secret like a password. Make sure to store it in a secure location.
- Select Done.
The new secret takes effect immediately for all new events. Update your signature verification routine with the new secret to continue processing webhook events.
Next steps
After rotating your webhook secret, consider the following next steps:
- Verify webhook signatures: Update your verification code with the new secret.
- Test webhook endpoints: Send test events to confirm your endpoint works with the new secret.
- Configure webhook events: Manage which events trigger notifications to your endpoint.