Fictional event sequence
Arrival order differs from record order.
For this example only, assume the source exposes a documented, increasing revision for each opportunity. Revision 18 follows revision 17 for O-204; it is not a sequence across all opportunities.
| Source change | Receiver arrival | Decision |
|---|---|---|
| O-204 revision 17: awaiting review | Second | Do not replace revision 18 with revision 17 |
| O-204 revision 18: approved | First | Apply approved after validating the record and revision |
| Revision 18 delivered again | Third | Recognise the same operation; avoid another onboarding task |
Choose for this workflow
Current state and transition history need different handling.
The receiver needs the latest status
If the source offers a suitable revision, compare it with the last applied revision for this record. Apply the update and its revision together, with a concurrency check so two workers cannot both overwrite the same state.
Without a usable revision, fetching the current opportunity may suit a current-state view. The lookup can fail or become stale before the write, so retain uncertainty and use the source contract rather than treating the lookup as a universal fix.
The workflow needs every transition
An approval may require an audit entry even when a later cancellation has already arrived. Replacing the notification with current state would hide that transition.
Use the documented history or sequence mechanism where available. If an earlier transition is missing, hold dependent work or investigate the gap. Choose that behaviour with the person responsible for the workflow; do not reconstruct a missing transition from a guess.
Check the record before applying the update.
01
Verify and identify the delivery
Validate the sender using its documented mechanism. Keep the record identity and event or delivery identity separate. GitHub documents secrets and delivery identifiers for its own webhooks.
02
Determine what establishes order
Use a documented source revision or sequence with the right scope. Arrival time shows when you received the request. A timestamp may tie or have unclear semantics, so it is not automatically a safe ordering key.
03
Make the write conditional
Compare the stored state and revision when committing the update, not only when the worker starts. Coordinate the state change with any task creation; a database transaction alone does not make an external API call atomic.
04
Keep an uncertain result visible
Record the reason an event was held or skipped and who should investigate. Follow the provider acknowledgement contract; durable receipt can succeed while the business decision remains pending.
Before release
Test more than the reversed pair.
Use fixtures rather than customer payloads when these cases can be modelled without them. Evidence retention and access rules need their own review.
| Test | Expected evidence |
|---|---|
| Revision 18 followed by revision 17 | State remains approved; the older event has a recorded decision |
| Two workers apply revisions 17 and 18 together | The conditional write preserves the agreed newer state |
| Two distinct events share a timestamp | The receiver does not invent an ordering guarantee |
| Current-state lookup fails | Work remains visibly pending; no guessed status is written |
| State write succeeds but task call times out | The operator can inspect the destination before replaying a possibly completed action |
