Webhook time parsing guidelines

Webhook Time Parsing Guidelines

This guide complements:

  • webhook-time-fields-map.csv
  • webhook-time-fields-strategy.csv

Scope: webhook-20260601004833.json (account display context UTC-6).

Core Rule

There are two distinct time semantics in the payload:

  1. UTC instants (event/audit moments)
  2. LocalBusiness date/times (schedule/service-day semantics)

Do not treat them the same.

UTC Fields (Event/Audit Time)

Typical examples:

  • created (epoch)
  • *.createdAt.value
  • *.updatedAt.value
  • departureTimestamp
  • arrivalTimestamp

Backend Do

  • Parse as UTC immediately.
  • Persist in UTC (ISO8601 Z or epoch).
  • Convert only at presentation boundaries.

Backend Don't

  • Don't reinterpret these using station/account timezone before storage.
  • Don't drop timezone information.

Data Team Do

  • Use these for event ordering, latency, SLA, and auditing.
  • Join cross-system events on these fields.

Data Team Don't

  • Don't use these alone as "service day" business keys.

LocalBusiness Fields (Schedule/Service Context)

Typical examples:

  • travelDate.value
  • departureDatetime.value
  • arrivalDate.value
  • manifestDate.value
  • expirationDate.value
  • productExpirationDate.value
  • cutOffDateTime.value
  • date
  • departureTime

Backend Do

  • Treat as business-local datetime/date values.
  • Carry timezone context (shiftLocation.timeZone, station timezone, or account timezone) with these fields.
  • Use these for schedule logic, ticket validity windows, and operational day rules.

Backend Don't

  • Don't blindly convert these as UTC instants just because a Z is present.
  • Don't compare these directly with audit UTC instants without normalization intent.

Data Team Do

  • Build service-day dimensions from LocalBusiness fields + timezone context.
  • Use explicit transformations when creating UTC analytics fields.

Data Team Don't

  • Don't mix LocalBusiness and UTC fields in the same metric without defining business intent.

Quick Identification Heuristics

  • If field is created, createdAt, updatedAt, or ends with Timestamp -> likely UTC.
  • If field is date, departureTime, manifestDate, travelDate, cutOffDateTime -> likely LocalBusiness.
  • Always prefer semantic field intent over string format.
  • Keep original payload fields as received (raw zone semantics preserved).
  • Add derived normalized columns:
    • *_utc for UTC-usable timestamps
    • *_local for business-local values
    • *_timezone for context

Example:

  • departureTimestamp -> departure_timestamp_utc
  • travelDate.value + shiftLocation.timeZone -> travel_datetime_local, travel_timezone

Validation Checks to Add

  • Assert departureTimestamp aligns with local departureTime after timezone conversion.
  • Flag records where service-day fields and UTC instants diverge beyond expected offset logic.
  • Log timezone source used for each normalization step.