A webhook signing secret authenticates incoming deliveries to one endpoint. It is separate from the API key used to manage that endpoint. Rotating one does not rotate the other.
Prepare the receiver first
Make sure the receiver loads its verification secret from protected configuration and can receive an update promptly. Identify who can perform the rotation, where the new secret will be stored and how you will verify delivery afterward.
The new secret is not available before the rotation operation issues it. Do not plan a procedure that requires deploying an unknown value in advance. Prepare the configuration path and deployment process instead.
Rotate and update configuration
Call rotate webhook secret. Capture the newly returned secret securely and update the receiver's configuration immediately. The service does not provide an old/new signing overlap period.
During the transition, a receiver still using the old value can reject a new delivery. Treat that as a recoverable delivery failure and inspect retries. If your own receiver temporarily supports both values to cover an in-flight request, limit that transition and remove the retired value promptly.
Verify the new configuration
Send a supported test ping, then confirm verification, durable acceptance and worker processing. Inspect delivery logs for failures around the rotation window.
Do not expose either secret in a screenshot or ticket while checking the result. Save endpoint and delivery IDs, statuses and timestamps instead.
Retire the old value
Remove the retired secret from active receiver configuration and from any temporary rollout mechanism. Keep incident or change records without storing secret values in ordinary notes.
If the rotation responds ambiguously because the connection fails, do not assume your receiver's current value is still the service's active secret. Investigate and coordinate recovery. A deliberate subsequent rotation can establish a known secret, but it is a new state change and should be handled as such.
For replacing a bearer credential rather than an incoming signature secret, use API credential rotation.