Rotating secrets

Rotate a secret when it may have leaked, when someone with access leaves, or on a schedule.

Rotate

curl -X POST \
  "https://api.officehero.io/v1/webhook_endpoints/$ENDPOINT_ID/rotate_secret" \
  -H "Authorization: Bearer $OFFICEHERO_API_KEY"

{
  "secret": "whsec_…",
  "secret_prefix": "whsec_N7bTr2",
  "secret_rotated_at": "2026-10-10T08:15:00Z"
}

The new secret is shown only in this response.

What changes, and when

• X-OH-Signature uses the new secret from the next delivery on. There is no overlap period on this header.
• Deliveries signed with the old secret in the seconds around the rotation fail your verification and are retried on the normal schedule — signed with the new secret. Nothing is lost.
• The legacy header (X-OH-Signature-Legacy, sent until 2026-12-17) carries signatures for both the old and the new secret for 24 hours after a rotation. Only receivers still on the legacy algorithm see this.
• Rotating also switches an endpoint whose canonical_signing_enabled was false to the documented signing algorithm.

A safe procedure

1. Call rotate_secret and keep the response.
2. Put the new secret into your receiver’s secret store and roll it out.
3. Watch GET …/deliveries: deliveries your receiver rejected around the switch stay pending and are retried with the new secret. If any ended failed (or dead), replay them.

If several services verify the same endpoint, consider a second endpoint per service instead of sharing one secret.