Network arrival order is not shipment state order. A delayed delivery or deliberate replay may reach your receiver after a newer update. An event’s carrier scan timestamp is also not a safe snapshot version, especially when the source omits a timezone.
Trace owned shipment snapshots carry an increasing revision. Shipment webhooks include shipment.revision and shipment_revision. Use that version to protect your projection, while deduplicating the event identity independently.
Separate three kinds of identity
The event ID answers whether you already accepted this event. The shipment ID identifies the record to update. The revision answers whether the incoming snapshot is newer than the saved one. A delivery attempt ID is useful for diagnostics, but cannot replace event-ID deduplication.
Verify the raw bytes and signature before trusting any of those values. Parse and validate the authenticated payload, then use the account-owned shipment mapping to locate the local projection.
Make the revision check atomic
An application-level check followed by an unconditional write has a race: two workers can both read the same old revision. Put the conditional update and durable event acceptance inside a transaction, using a uniqueness constraint for the event ID.
SQL sketch · adapt names to your own projection schema
BEGIN;
-- Insert the verified event into a durable inbox with a unique event_id.
-- If it is already accepted, acknowledge without applying it again.
UPDATE shipment_projection
SET revision = :incoming_revision, snapshot = :validated_snapshot
WHERE tenant_id = :tenant_id
AND shipment_id = :shipment_id
AND revision < :incoming_revision;
-- Commit the inbox outcome even when an older revision changes no rows.
COMMIT;Fetch authoritative state when a version is absent
For older payloads without a revision, read the authoritative owned shipment through your server rather than guessing state order from scan time or delivery time. Reconciliation is also useful when a consumer recovers after an outage.
Revision ordering applies to the owned shipment projection. Do not invent a comparable revision for a direct tracking response that lacks one. Preserve immutable scan history separately from whichever snapshot is currently displayed.
Rehearse reverse arrival and replay
Apply revision 8, then deliver revision 7 and verify the projection remains at 8. Replay the event for revision 8 and verify that buyer notifications are not sent twice. Send two revisions concurrently to check the database condition, and test a valid older payload without a revision.
A stale snapshot should not overwrite a newer one merely because it arrived later. Likewise, an updated normalization identity does not necessarily mean a second physical carrier scan; notification logic needs its own business rule.
Common questions
Can I sort webhooks by the carrier event timestamp?
Not safely for snapshot ordering. Scan time describes source evidence and can be missing or local-only. Use the shipment revision for owned records.
References & next steps
Implementation details were checked against Trace’s current API. External product details may change; verify the linked documentation before deciding.