Operational Experience

Key Rotation

Webhooks rely heavily on secrets — hash keys, tokens, certificates — that should be rotated periodically to keep communications safe. Good webhook implementations recognize this necessity and implement features to simplify and automate the key rotations:

Providers — like Box, Brex, Docusign, and PagerDuty — implemented controls within their webhooks for key rotation.

PagerDuty, for example, can sign webhooks using multiple signatures and then add them all to the X-PagerDuty-Signature header (comma separated), allowing consumers to roll out a new secret key and gradually update webhook listeners without outages.


Box and Docusign enumerate signatures as part of the header name:

BOX-SIGNATURE-SECONDARY: v+1CD1Jdo3muIcbpv5lxxgPglOqMfsNHPV899xWYydo=
X-DocuSign-Signature-1: DfV+OtRSnsuy.....NLXUyTfY=
X-DocuSign-Signature-2: CL9zR6MI/yUa.....O09tpBhk=
X-DocuSign-Signature-#: CLdaoskdi_kd.....O09tpskk=

Plaid goes one step further and implements the JSON Web Key (JWK) standard for rotating keys. While JWK adds extra complexity during the development, it provides a way for webhook consumers to fetch the latest keys used by Plaid to sign webhook messages.

Forward Compatibility