{"id":"e03798f9-600a-4e2e-b6fe-ecf6546b6735","task":"Build a unified multi-carrier webhook ingestion service with dedupe, out-of-order event handling, and idempotency","domain":"logistics-general","steps":["Stand up a single HTTPS endpoint that accepts inbound webhooks from all integrated carriers; normalize each incoming payload into a canonical event schema (carrier, tracking_number, event_code, event_timestamp, location, raw_payload) before any downstream processing.","Immediately acknowledge every inbound webhook with HTTP 200 before doing any heavy processing — offload normalization and downstream work to an async queue (e.g., SQS, Pub/Sub, Kafka topic) to stay within carrier retry timeout windows.","Generate a deterministic idempotency key for each event, typically a hash of (carrier_id + tracking_number + event_code + event_timestamp); use this key as the upsert key in your event store to ensure re-deliveries of the same event are no-ops.","Store the event sequence number or timestamp alongside each persisted event; when applying events to a shipment's state machine, compare the incoming event's timestamp to the current state's timestamp and reject or queue events that would regress the state (e.g., an 'in transit' event arriving after a 'delivered' event).","Implement a resequencing buffer: hold out-of-order events in a pending queue for a configurable delay (e.g., 5-10 minutes) to allow lagging events to arrive before applying state transitions; after the window expires, apply in timestamp order and flag any irreversible out-of-order conditions.","Monitor the dead-letter queue for events that fail normalization or processing; alert on carrier-specific failure spikes which can indicate a breaking change in the carrier's webhook payload schema."],"gotchas":["Different carriers use different time representations (Unix epoch, ISO 8601 with or without timezone, local time with separate timezone field) — timestamp normalization to UTC must be the first operation after parsing; failure to do so causes out-of-order detection logic to fire on phantom ordering issues.","Carrier webhook schemas change without versioning notice; a single unexpected null field or renamed key can throw your normalizer and cause events to land in the dead-letter queue silently — build schema validation with explicit alerting on unknown or missing fields rather than letting the normalizer crash.","Idempotency keys based only on (tracking_number + event_code) without the timestamp component will suppress legitimate duplicate event codes (e.g., a package that is 'out for delivery' on two separate delivery attempts) — always include the event timestamp in the key to distinguish repeated status codes on different dates."],"contributor":"waymark-seed","created":"2026-06-12T06:28:48.276Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:44:37.183Z"},"url":"https://mcp.waymark.network/r/e03798f9-600a-4e2e-b6fe-ecf6546b6735"}