Carrier Integration and Tracking Events

The real problem: a webhook arrived, but do we actually know shipment state?

A carrier may resend the same event, deliver an older event after a newer one, move an ETA, rename human-readable status text, or expose an event only in a later pull response. If business logic maps strings such as Delivered or In transit directly into internal order state, the first vendor change can corrupt your state machine. This lesson builds Carrier Tracking Normalization and Reconciliation Ledger v1: keep provider evidence immutable, separate identity and time dimensions, detect duplicates and late events, normalize through provider adapters into a small internal vocabulary, and reconcile push with pull.

Lesson boundary

COM-034 owns carrier-event truth, normalization, and reconciliation. COM-033 owns barcode/QR scanning UX and decoded identity. COM-035 owns customer-notification projection and Minimal PII. This lesson performs no live carrier subscription, shipment mutation, billing action, or real customer messaging.

Three hard boundaries:

1. Provider text is not a canonical key. It is descriptive evidence, not your state machine.
2. ETA is not proof of delivery. It remains estimate evidence.
3. Webhook arrival order is not event order. Keep received_at separate from provider_event_time.

Mental model: Receive → Authenticate → Append → Dedupe → Order → Normalize → Reconcile → Project

Treat every incoming payload as evidence first, not as final business truth:

provider payload → authenticity/subscription check → immutable event append → dedupe → event-time ordering → provider adapter → normalized state → push/pull reconciliation → bounded customer projection

provider_event_time expresses when the carrier says the event occurred; received_at expresses when your system received the payload. Preserving both lets you reason about late delivery, outages, replay, and ordering without rewriting history.

Keep FACT, INFERENCE, and DESIGN separate

FACT: DHL Unified Push v1.2.5 documents proactive status and delivery-time/routing notifications. FedEx AIV documents near-real-time tracking webhooks. GS1 EPCIS provides a visibility-event model and distinguishes event-time semantics from repository record-time bookkeeping.

Freshness correction: DHL announced a 2026 Parcel Germany change adding explicit timezone offsets and standardized descriptions, then temporarily reverted the release after a performance problem. The lesson is not “DHL now always sends offsets.” The lesson is that provider formats and descriptive text can change—and even roll back.

INFERENCE: multi-carrier systems are more resilient when provider identity/code/text, event time, receive time, dedupe identity, normalized state, estimate evidence, and customer projection remain separate.

DESIGN: MAKNOW uses a small canonical vocabulary, explicit UNKNOWN/EXCEPTION/ESTIMATE_ONLY states, push/pull reconciliation, and no delivery promotion from ETA or descriptive text alone.

The 25-field tracking contract

Gate 1 — Establish event identity before state

Use a stable provider event identifier when available. Otherwise, define a versioned dedupe_key from stable fields. Human-readable text is a poor dedupe key because providers can rename it. payload_digest proves exact payload bytes/content, not semantic identity by itself.

Gate 2 — Record authenticity and subscription context

A webhook event needs evidence of the account/subscription/channel and the authenticity control used. Missing decisive authenticity evidence fails closed to HOLD or UNKNOWN.

Gate 3 — Keep event time separate from receipt time

An event that occurred at 10:00 may arrive after an event that occurred at 10:05. Canonical ordering uses event semantics while receipt time remains visible for observability and incident analysis.

Gate 4 — Append duplicate evidence, but do not repeat business transitions

Do not erase duplicates from the audit trail. Mark them as duplicate and link them to the existing semantic event. They must not repeat state transitions, notifications, or other side effects.

Gate 5 — A late older event must not regress canonical state

If your canonical cursor already includes an out-for-delivery event at noon, a newly received 11:30 in-transit event may be real evidence, but it must not roll the state backward.

Gate 6 — Use provider adapters, not provider-string conditionals

Each carrier adapter maps (provider_event_code + context) into normalized event types and states. Human-readable text remains detail. Unknown codes become UNKNOWN; never implement delivery as if "delivered" in text.lower().

Gate 7 — Keep ETA in a separate lane

estimated_delivery_at and estimate_confidence_or_source are prediction evidence. ETA can change without a lifecycle transition. DELIVERED requires explicit, authenticated delivery evidence.

Gate 8 — Push and pull are complementary

Push reduces latency; reconciliation pull measures completeness. When a scheduled pull finds an event absent from the push ledger, record RECONCILIATION_GAP and append that event with pull provenance.

Gate 9 — Customer projection comes from normalized truth

Only safe, bounded fields should cross into customer projection. Raw provider payload and internal exception detail stay out. COM-035 owns the final notification/PII decision.

Gate 10 — Missing decisive evidence fails closed

Missing authenticity, mapping, event-time, or evidence reference is not permission to manufacture success. HOLD, UNKNOWN, and DISPUTED are valid operational states.

Worked examples

1. Authenticated push with a known code → IN_TRANSIT

The event is authenticated, code-mapped, uniquely identified, and time-stamped. The normalized state becomes IN_TRANSIT; provider text remains descriptive detail.

2. Same event is replayed → DUPLICATE

The event ID/dedupe key matches existing evidence. Keep the replay for audit, but do not mutate canonical state or repeat side effects.

3. Older event arrives later → OUT_OF_ORDER

Receipt time is newer, event time is older than the canonical cursor. Append evidence; do not regress state.

4. ETA moves → ESTIMATE_ONLY

Record the new estimate. Even if descriptive text contains the word “delivered,” do not promote without a delivery event code/type.

5. Pull reveals a missing event → RECONCILIATION_GAP

Append the pull-only event with source provenance and keep the visibility gap observable.

6. Add a second carrier

Create a second adapter. Reuse the shared tracking schema. Do not grow business logic into carrier-specific text branches.

Common failure modes

• Direct provider-string-to-state mapping.
• Treating receipt order as event order.
• Duplicate webhooks causing repeated side effects.
• Promoting ETA/window data into DELIVERED.
• Text-based delivery detection.
• Push-only architecture with no reconciliation.
• Parser assumptions that today's enums are exhaustive forever.
• Reusing carrier-one mapping for carrier two without recomputation.

Alternatives and trade-offs

Push only: low latency, weaker completeness/recovery evidence.

Polling only: simpler recovery and control, but higher latency/traffic and cadence/rate-limit cost.

Push + reconciliation pull: more moving parts, but separates latency from completeness and is the default pattern in this lesson.

Universal provider strings: quick demos, brittle production behavior. Provider adapters + normalized vocabulary cost more up front but contain vendor change.

Single timestamp: cheaper schema, weaker incident/audit semantics. Event time + receipt time is the evidence-preserving choice.

Experienced bridge: ten review questions

1. Is event identity stable or accidentally text-based?
2. Where is authenticity/subscription evidence stored?
3. Can a duplicate repeat a side effect?
4. Which timestamp controls canonical ordering?
5. What happens when a new provider code appears?
6. Is ETA isolated from lifecycle state?
7. Can a late event regress state?
8. What exactly does the reconciliation cursor prove?
9. Which provider-specific details are excluded from customer projection?
10. When carrier two arrives, what is reused and what must be recomputed?

Guided and independent practice

Run the eight offline fixtures: baseline, duplicate, out-of-order, ETA-only, description-change, pull-only gap, missing-auth, and second-carrier transfer. Do not focus only on the expected label. Identify the evidence dimension that changed the decision.

Then create a new fixture with an unknown provider code and persuasive “delivered” text. A correct solution must not use text search. Add a second carrier and change only the adapter; the shared tracking schema and business logic should remain stable.

Verification evidence

An acceptable artifact contains:

• all 25 contract dimensions or an explicit nullable rationale;
• duplicate and out-of-order handling without incorrect canonical mutation;
• mapping based on provider code/context rather than free text;
• ETA isolated in an estimate lane;
• push/pull reconciliation with a cursor;
• bounded customer projection separated from raw payload;
• evidence references for decisive transitions;
• second-carrier transfer without provider-string business branching.

The lab is deterministic and offline: no API key, live shipment, or network access is required.

Assessment and transfer

You must independently be able to: explain the COM-034 boundary and one adjacent non-goal; build the baseline ledger; diagnose duplicate/out-of-order mutations and minimal repair; and add carrier two through a new adapter without copying carrier-one string rules.

Copying a baseline decision without recomputing changed evidence fails transfer.

References and freshness

• DHL Shipment Tracking Unified Push v1.2.5 — current push/subscription/status evidence; review due 2026-10-18.
• DHL Parcel Germany 2026 backend notice — announced timestamp/text change and later rollback; used as volatility evidence, not a guarantee of current format.
• FedEx Advanced Integrated Visibility — near-real-time webhook/event evidence; current operational announcements show delay/republish incidents can occur, so completeness is not inferred from “near real time.”
• GS1 EPCIS 2.0.1 — current visibility-event standard and event-time/record-time semantics.

External sources establish FACTs only. Canonical states, promotion rules, and reconciliation policy remain MAKNOW design authority.