Aglet

Learn from webhook secret rotation gaps

The durable lesson is a rotation contract connecting endpoint, environment, secret version, secure configuration, deployment, verifier, and old-value retirement. Preserve the failed delivery and rollout boundary that exposed the gap. Record external overlap timing as a limit for every endpoint.

Keep the lesson for the next incident

  1. Document rollover rules

    Record endpoint and environment, version labels, configuration ownership, deployment order, overlap or retirement policy, verification result, retry, and quarantine. Define what can be logged safely. Keep secret values out of the contract.

  2. Keep rotation fixtures

    Retain old, new, overlap, expired, wrong endpoint, missing configuration, restart, and failed-delivery cases with synthetic labels. Store expected verification and effect state. Retain the timing of the original configuration gap, including which verifier accepted each synthetic key label before and after restart.

  3. Review secret signals

    Watch verification failures after rotations, stale version labels, missing config, wrong endpoints, pending deliveries, and unverified processing by receiver revision. Assign an owner and threshold. Close only when every endpoint has transition coverage. Keep rejected and pending counts separate.

What to carry forward

Close learning with rollover rules, safe fixtures, configuration and deployment owners, and rotation signals. Keep secret material and external timing limits explicit. The useful outcome is strict verification with a reviewable pending path. Review receiver deployments before retiring an old version.

Technical background: Stripe documentation.

Keep the decision with the work.

Use a Work Item in Aglet to record the problem, the evidence you have, and the next decision. Add an owner and priority, then keep updates in the discussion so the next person can follow the reasoning.

Create an account See the product workflow