¶ UseCase

The Real-Time Status Change webhook is a crucial mechanism for fleet suppliers, enabling them to monitor driver status changes in real time. It triggers various status transitions throughout the complete trip lifecycle, such as offline to online, online to enroute, arrival at pickup, on trip, drop-off completion, and others, providing timely updates for all fleet drivers under the given Organization UUID. This webhook provides immediate notifications to applications whenever a driver status changes. This allows the application to react instantly to status updates, without the need for continuous polling. By receiving these real-time updates, it maintains up-to-the-minute accuracy and reduces server load, making it ideal for live monitoring and alerting systems. For more information on how to utilize webhooks, please refer to the provided link here.

¶ Event Types

This webhook supports two event types:

• REALTIME_STATUS_CHANGE (Recommended) - New standardized event type with simplified status values
• REALTIME_DRIVER_STATUS_CHANGE (Legacy) - Existing event type maintained for backward compatibility

Note: New integrations should use REALTIME_STATUS_CHANGE. Existing integrations using REALTIME_DRIVER_STATUS_CHANGE will continue to work without any changes.

¶ Supported Supplier Types

Fleets

¶ Support for Hierarchical Data

The Real-Time Driver Status Change webhook supports hierarchical data within the fleet hierarchy, enabling efficient monitoring and management of status changes across different organizational levels.

¶ Authentication

None. Auth process defined here.

¶ Request Header Parameters

Defined here

¶ Webhook Response Fields

Name	Type	Description
driver_id	string	Raw unique identifier for the driver
event_id	string	Unique event identifier ensuring event uniqueness
event_time	long	Unix timestamp indicating when the status change event occurred
event_type	string	Specifies the type of event that occurred. Can be REALTIME_STATUS_CHANGE (new) or REALTIME_DRIVER_STATUS_CHANGE (legacy)
location	object	Contains Location coordinates representing the location when the status change event occurred
org_id	string	Encrypted Organization ID
status	string	Indicates the current Status of the driver
vehicle_id	string	Raw unique identifier for the vehicle.
webhook_meta	object	Additional Meta related to the webhook
resource_href	string	URL pointing to the endpoint

Location

Name	Type	Description
latitude	float	The latitude coordinate of the location when status change event occurred.
longitude	float	The longitude coordinate of the location when status change event occurred.

Status

The status values depend on the event type:

For REALTIME_STATUS_CHANGE (New - Recommended)

Status	Definition
STATUS_ONLINE	If the earner is online, but not on any active job
STATUS_OFFLINE	If the earner is offline
STATUS_ENROUTE	If the earner is on the way for pickup
STATUS_ONTRIP	If the earner is on any leg of the job
STATUS_UNASSIGNABLE	If the earner is temporarily unavailable for new assignments
STATUS_ARRIVED	If the earner has arrived at the pickup location
STATUS_DROPPED_OFF	If the earner has completed the drop-off

For REALTIME_DRIVER_STATUS_CHANGE (Legacy - Backward Compatibility)

Status	Definition
DRIVER_STATUS_ONLINE	If the driver is online, but not on any active trip
DRIVER_STATUS_OFFLINE	If the driver is offline
DRIVER_STATUS_ENROUTE	If the driver is on the way for pickup
DRIVER_STATUS_ONTRIP	If the driver is on any leg of the trip

Meta

Name	Type	Description
client_id	string	The ID of the client associated with the webhook.
webhook_config_id	string	The ID of the webhook configuration.
webhook_msg_timestamp	long	Unix timestamp indicating when the webhook message was sent
webhook_msg_uuid	string	Unique identifier for the webhook message

¶ Example

Example 1: New Event Type (REALTIME_STATUS_CHANGE)

{
    "driver_id": "1a8e9cf5-ee45-4c8a-a5cd-7d32c9515d72",
    "event_id": "6f0d8726-3b25-4e6e-9268-5ab6c3a78b4f",
    "event_time": 1697253089123,
    "event_type": "REALTIME_STATUS_CHANGE",
    "location": {
        "latitude": 38.899349,
        "longitude": -122.414592
    },
    "org_id": "9t54qzKl3pRg7UdY_O5DlLOH3t3oOcNdK3pIW1q6NiJ8KxGbsAV-C9lWtT6T1qlpGQ6SHobVJJaO2lUiBU3G5M-wOggAMz8NqToBlNQVr90uaLiDLbU9P9xAtdTFqinNw==",
    "resource_href": "https://api.uber.com/v1/vehicle-suppliers/realtime/driver/status/change",
    "status": "STATUS_ARRIVED",
    "vehicle_id": "c50b508a-7040-4a77-b290-8f8c2c96f43d",
    "webhook_meta": {
        "client_id": "a3ef6mCIqspWQgyFFexMVTgbRKMwNlF0",
        "webhook_config_id": "vehicle-solutions.ep-realtime-status-change",
        "webhook_msg_timestamp": 1699877427,
        "webhook_msg_uuid": "670532a8-ca01-4b4f-b145-d7ca5d945448"
    }
}

Example 2: Legacy Event Type (REALTIME_DRIVER_STATUS_CHANGE)

{
    "driver_id": "1a8e9cf5-ee45-4c8a-a5cd-7d32c9515d72",
    "event_id": "6f0d8726-3b25-4e6e-9268-5ab6c3a78b4f",
    "event_time": 1697253089123,
    "event_type": "REALTIME_DRIVER_STATUS_CHANGE",
    "location": {
        "latitude": 38.899349,
        "longitude": -122.414592
    },
    "org_id": "9t54qzKl3pRg7UdY_O5DlLOH3t3oOcNdK3pIW1q6NiJ8KxGbsAV-C9lWtT6T1qlpGQ6SHobVJJaO2lUiBU3G5M-wOggAMz8NqToBlNQVr90uaLiDLbU9P9xAtdTFqinNw==",
    "resource_href": "https://api.uber.com/v1/vehicle-suppliers/realtime/driver/status/change",
    "status": "DRIVER_STATUS_ENROUTE",
    "vehicle_id": "c50b508a-7040-4a77-b290-8f8c2c96f43d",
    "webhook_meta": {
        "client_id": "a3ef6mCIqspWQgyFFexMVTgbRKMwNlF0",
        "webhook_config_id": "vehicle-solutions.ep-realtime-driver-status-change",
        "webhook_msg_timestamp": 1699877427,
        "webhook_msg_uuid": "670532a8-ca01-4b4f-b145-d7ca5d945448"
    }
}

¶ Webhook Security

For detailed information on securing webhooks, please refer to the security guidelines here.

¶ Retry

If Uber does not receive an acknowledgement response, the event will be resent based on an exponential backoff algorithm. The next webhook event will be sent 30 seconds after the initial event, then again after 60 seconds,120 seconds, and so on. 7 retries will be made with this exponential backoff.

¶ Backfill Process

The backfill process is a critical component of ensuring uninterrupted data flow in case of client webhook failures. This process introduces a new report type within the offline reporting APIs specifically designed for backfill scenarios. When the client’s webhook experiences downtime or fails to respond successfully to webhook events, the backfill process comes into play.

In such situations where webhooks are not sending, rate-limiting occurs, or there is an exhaustion of webhook events without receiving a successful response code from the client, failed webhook events are logged and can be retrieved using the offline reporting APIs

¶ Sand Box

Please note that sandbox support is currently unavailable.

¶ FAQ

• Does the Webhook support sandbox environments?

  • No, the webhook does not currently support sandbox environments.

• Which event type should I use?

  • New integrations should use REALTIME_STATUS_CHANGE with STATUS_* values. This is the recommended and standardized format.
  • Existing integrations can continue using REALTIME_DRIVER_STATUS_CHANGE with DRIVER_STATUS_* values.

• What’s the difference between the two event types?

  • REALTIME_STATUS_CHANGE (new) provides enhanced trip lifecycle tracking with 7 statuses including STATUS_ARRIVED and STATUS_DROPPED_OFF, and uses simplified status naming (e.g., STATUS_ONLINE).
  • REALTIME_DRIVER_STATUS_CHANGE (legacy) provides 4 basic statuses with the DRIVER_STATUS_ prefix (e.g., DRIVER_STATUS_ONLINE).
  • The new event type offers more granular tracking for better real-time visibility.

• Do I need to migrate from the legacy event type?

  • No, migration is optional. The legacy REALTIME_DRIVER_STATUS_CHANGE event type will continue to be supported for backward compatibility. However, new integrations are encouraged to use REALTIME_STATUS_CHANGE.

• Can we onboard multiple webhooks?

  • Yes, while configuring other webhook urls, a developer_uuid + webhook_url + signing_key is required which has to be updated by Supplier on Developer Dashboard. This developer_uuid needs to be passed in Payload through code if we want to onboard other webhook urls apart from primary.
  

• If one particular organization has many drivers, will they receive that many event notifications?

  • For a single driver, there will be multiple notifications each time the status changes.
  • For the new event type (REALTIME_STATUS_CHANGE), at least 5 notifications are expected per trip (e.g., ONLINE → ENROUTE → ARRIVED → ONTRIP → DROPPED_OFF).
  • For the legacy event type (REALTIME_DRIVER_STATUS_CHANGE), at least 3 notifications are expected per trip (e.g., ONLINE → ENROUTE → ONTRIP).