Uber Direct facilitates real-time delivery updates by notifying your application through Webhooks. This guide outlines the step-by-step process for setting up, receiving, authenticating, and processing these notifications.

¶ Set Up the Webhooks Endpoint

Webhook notifications are sent as POST requests from Uber Direct to an Internet endpoint that you specify. When your endpoints are up and listening, you can add the endpoint URLs via the Uber Direct Dashboard (direct.uber.com).

Please provide one or more URLs to Uber if you would like to receive Webhooks.

1. Click the Developer tab on the left, followed by the Webhooks tab.
   
2. Click Create Webhook.
   During this step, you have the opportunity to select the appropriate type of Webhook for each URL. For detailed explanations regarding the event.delivery_status and event.courier_update, please refer to the following resources:
   • event.delivery_status explanation
   • event.courier_update explanation
   • event.refund explanation
3. Fill in the Webhook URL with your service endpoint.
   IMPORTANT: For security concern, you’ll need to configure your own web application to accept HTTPS requests from us.
4. Choose which Webhook(s) should be sent to this URL. You can use one URL for all Webhook types or a separate URL for each.
5. Click Save.

¶ Authenticating Webhooks

Upon creating a Webhook, you will be provided with a dedicated Webhook Signing Key. This confidential key serves as a shared secret between your application and Uber, ensuring the authenticity and integrity of incoming messages to your Webhook endpoint.

To obtain the signing key for a specific Webhook, navigate to the respective Webhook entry and click on the triple dots symbol. From the dropdown menu, select the “Edit” option.

When a Webhook POST message is sent to your endpoint, it includes the header x-uber-signature, which is a SHA-256 hash of the message payload generated using the signing key. You can use the following steps to verify the Webhook message:

1. Compute the SHA-256 HASH of the message utilizing your designated signing key. It is recommended to employ a standard HMAC function provided by your programming language.
2. Validate the checksum by comparing it to the hash value present in the x-uber-signature header. If the checksum matches the hash value, proceed with processing the message as intended. Otherwise, ignore it.

It is crucial to ensure the integrity and authenticity of the message by confirming the checksum validity before proceeding with any processing.

Here is an example of a Python script that computes what the x-uber-signature should be, given a signing key and a message payload:

import hashlib, hmac

signing_key = 'c5c26d5a-70d6-46c7-a652-d7c09825ad29'

# Shortened for this example
payload = '{"kind": "event.courier_update", "location": {"lat": 37.7974109, "lng": -122.424145}}'

hmac.new(signing_key.encode('utf-8'), payload.encode('utf-8'), hashlib.sha256).hexdigest()

# → 'cdff8133fb065f8d37a2c1c94c3331b6a82766d14e7ea4faacc4886558cedd65'

IMPORTANT

1. In the Delivery Status Webhook and Courier Update Webhook, you can use either x-uber-signature or x-postmates-signature for the above verification. However, for the Refund Webhook, please ensure you use x-uber-signature for verification.
2. Avoid Unintended Character Conversion in JSON/String Parsing:
   When handling the webhook’s body, please be aware that it might contain escape sequences for Unicode characters like \uXXXX. Ensure that your parsing methods maintain the original raw format. Some parsing functions may unintentionally convert escape sequences into their respective characters (e.g., \u0026 to &). Choose parsing methods or libraries that preserve the original format to prevent unexpected conversions. Testing with inputs containing escape sequences helps confirm the integrity of your parsing functions.

¶ Retry logic

If Uber receives either of 500, 502, 503, 504 status codes, timeout or any network error, the webhook event will be retried. The first retry will be sent 10 seconds after the initial event. The following events will be resent based on an exponential backoff algorithm, starting at 30 seconds after the 10s retry, then again after 60 seconds, then after 120 seconds, and so on until a response is received or until 3 total events were sent without a response.

If the the webhook is not received due to another status code, the recommendation is to use the Get Delivery endpoint to retrieve the data of the trip.