Aglet

Learn from out-of-order webhook events

The durable lesson is an explicit rule for event order, resource version, and stale state. Preserve the competing deliveries and the guard that resolved them. Document where ordering is undefined, where readback is required, and which transitions cannot proceed on ambiguous evidence.

Keep the lesson for the next incident

  1. Document ordering semantics

    Record resource key, event identity, version or sequence, timestamp use, receipt order, stale disposition, duplicate behavior, and reconciliation path. State whether the contract guarantees order per resource or leaves it open.

  2. Keep permutation fixtures

    Retain ordered, reversed, concurrent, duplicate, equal-time, missing-version, and advanced-state cases. Store expected comparison and final state. Include the original stale transition for future handler or storage changes for that resource.

  3. Review stale-write signals

    Watch rejected stale events, versionless deliveries, reversals, equal-time conflicts, and reconciliation use by endpoint and resource. Assign an owner and threshold. Close the follow-up only when state-changing handlers run the permutations.

What to carry forward

Close learning with ordering semantics, permutation fixtures, handler ownership, and stale-write signals. Keep undefined sender order visible. The useful outcome is a deliberate stale rejection or readback path, not a promise of global ordering. Review each state-changing handler against the permutation fixtures. Keep resource history available.

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