generated: '2026-08-22'
method: searched
source: >-
  https://hypertrack.com/reference/webhooks,
  https://hypertrack.com/docs/stream-order-activity-markers-via-webhooks,
  https://github.com/hypertrack/hypertrack-skills (skills/hypertrack-integration/references/webhooks.md)
type: Webhooks
asyncapi_published: false
asyncapi_note: >-
  HyperTrack publishes no AsyncAPI document. Probed 2026-08-22:
  https://hypertrack.com/reference/asyncapi.yaml (404), https://hypertrack.com/asyncapi.yaml (404),
  https://v3.api.hypertrack.com/asyncapi.json (404). The event surface below is real and
  substantial; it is simply documented in prose and JSON examples rather than as a machine-readable
  event contract. None was authored on the provider's behalf.
transport:
  protocol: HTTPS POST to a customer-hosted endpoint
  configuration: >-
    Configured in the HyperTrack dashboard; requires a static, always-reachable public HTTPS
    endpoint.
  content_type: application/json
  body_shape: JSON array of event objects (batched)
  ack: respond with a status code in the 200-4xx range within 10 seconds
  retries: up to 3 retries, 20 seconds apart
  dedup: >-
    Retries carry the same x-amz-sns-message-id; the provider recommends storing processed message
    IDs. For order events the recommended dedup key is order_handle + data.value + recorded_at.
  ordering: >-
    Best effort. Delivery order is not guaranteed; consumers should order on recorded_at.
  signature:
    header: x-hypertrack-signature
    algorithm_published: false
    note: The header is named in the reference; the signing algorithm is not spelled out on the public page.
envelope:
  fields:
  - name: device_id
    note: Present on device-originated events; case sensitive.
  - name: created_at
    note: ISO 8601, server time the webhook was sent.
  - name: recorded_at
    note: ISO 8601, client time the event was recorded. Absent on trip webhooks.
  - name: type
    note: The event type.
  - name: data
    note: Type-specific payload object.
  - name: location
    note: GeoJSON. Present on location and trip-delay events.
  - name: version
    note: Webhook payload version string (e.g. "2.0.0").
event_types:
- type: location
  description: Location stream from the tracked device.
- type: device_status
  description: Device active / inactive / disconnected transitions and activity changes.
  subtypes: [active, inactive, disconnected]
- type: battery
  description: Battery level transitions (low, normal, charging).
- type: geotag
  description: Geotags generated by app users, with route_to distance, duration and start_location.
- type: geofence
  description: Geofence entry and exit markers.
- type: trip
  description: Trip lifecycle.
  values: [created, destination_arrival, destination_exit, delayed, first_eta, eta_change, completed]
- type: order
  description: Order lifecycle.
  values: [planning_started, planning_completed, planning_failed, started, assigned, first_eta, eta_change, delayed, n_minutes_away, disabled, enabled, updated, arrived, exited, completed, cancelled, device_switched, on_device_geofence_checked, risk_updated, billing_details_updated, timesheet_updated, location_timesheet_finalized]
- type: route
  description: Route lifecycle.
  values: [created, assigned, estimate_generated, started, completed, updated, request_version_missing, candidate_devices_updated]
- type: worker
  description: Worker and device lifecycle.
  values: [tracking_started, work_status_updated, outage_started, outage_ended, device_disconnected, device_connected, device_linked, device_unlinked]
- type: registration
  description: Initial device registration.
- type: registration_update
  description: Device info or metadata update.
- type: reinstall
  description: Application reinstallation detected.
- type: time_offset_changed
  description: Device clock manually changed by more than 10 minutes (tamper signal).
- type: nearby
  description: Nearby API request completion notification.
event_type_count: 14
order_event_value_count: 22
outage_reasons:
  note: >-
    Enumerated values of device_status.data.reason on an `inactive` device_status event, published
    verbatim at https://hypertrack.com/docs/stream-order-activity-markers-via-webhooks.
  values:
  - airplane_mode_detected
  - location_permissions_denied
  - location_services_disabled
  - low_battery
  - motion_activity_permissions_denied
  - motion_activity_services_disabled
  - motion_activity_services_unavailable
  - push_token_missing_to_start_tracking
  - tracking_stopped
  - tracking_service_terminated
  - deleted
  - uninstalled
  - location_unavailable
  - location_unavailable_battery_saver
  - location_unavailable_provisional_authorization
  - sdk_killed_low_memory
  - sdk_killed_by_user
  - sdk_killed_by_app_update
  - sdk_killed_by_permissions_activity
  - sdk_killed_by_permissions_location
  - sdk_killed_by_os_update
  - sdk_killed_by_os_reboot
  - sdk_killed_by_low_power
  - storage_unavailable
  - network_limit_reached
  - location_permission_asked_in_background
  - location_permission_restricted
  - motion_activity_permission_not_determined
  - motion_activity_permission_asked_in_background
  - location_permission_not_determined
  - location_permission_imprecise
related_rest:
  operation: GET /orders/{order_handle}/webhooks
  note: Replays the webhook events recorded for a single order; also exposed as the MCP tool get_order_webhooks.