Webhooks
Rental platform supports multiple webhooks to which rental companies can subscribe to get updates corresponding to their vehicles/drivers/contracts etc. Go to the API Reference to get more details about a specific webhook.
¶ Subscribing to a webhook
¶ 1. Expose a new HTTP POST endpoint
Rental companies will need to expose a HTTP POST endpoint which would be used by Uber to send callbacks. This endpoint should support the following API schema.
¶ Request Path Parameters
| Name | Type | Description |
|---|---|---|
| - | - | - |
¶ Request Header Parameters
| Name | Type | Value | Description |
|---|---|---|---|
| Content-Type | string | application/json | The content type is JSON |
| X-Uber-Signature | string | A hexadecimal HMAC signature of the webhook HTTP request body, using the client secret as a key and SHA256 as the hash function | This signature should be verified to make sure the events are really from Uber. |
| X-Environment | string | production or sandbox | Indicates if this request is coming from the production or sandbox environment. |
¶ Request Query/Body Parameters
| Name | Type | Description |
|---|---|---|
| event_id | string | Unique event identifier, which can be used to ensure that events are only digested once. This is a Uber generated UUID. |
| event_time | integer | Unix timestamp of the time the event occurred. |
| event_type | string | The type of event that occurred. |
| meta | object | The object containing additional information that is specific to the event_type. Go to the documentation of the specific webhook in the API Reference (e.g.) section to check the meta for the corresponding webhook. |
¶ 2. Register the webhook URL in the developer dashboard
Register the URL of the HTTP POST endpoint in the developer dashboard application under the Settings/RIDE REQUESTS/Webhook URL section.
¶ 3. Subscribe request for the webhooks
Subscription to a webhook is a manual process. Follow up with your Uber POC for the webhook subscription with the list of webhooks required.
¶ Authentication requirements for webhooks
Uber webhook framework doesn’t support OAuth access mechanism while calling partner’s endpoints. Here is how you can check for the authenticity of the API call (if Uber is calling the webhook endpoint):
-
Uber will generate a hexadecimal HMAC signature of the webhook HTTP request body using the client secret (for the application registered on developer dashboard) as the key and SHA256 as the hash function.
-
This HMAC signature will be sent with the webhook as X-Uber-Signature header field.
Rental company can similarly generate this value on their side and compare both the signatures. If the signatures doesn’t match, the API call can be discarded.
¶ Expected response
Your service should respond with a 200 response status code with an empty response body to acknowledge receipt of the webhook event. If no acknowledgement is received, Uber will continue to retry the webhook according to the retry logic described below.
¶ Retry logic
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, then after 120 seconds, and so on. A total of 7 retries will be made with this exponential backoff.
¶ 4. Webhook Security Guidelines
Uber webhook framework doesn’t support OAuth access mechanism while calling partner’s endpoints. Here is how you can check for the authenticity of the API call (if Uber is calling the webhook endpoint): Uber will generate a hexadecimal HMAC signature for the webhook HTTP request body using the client secret (for the application registered on developer dashboard) as the key and SHA256 as the hash function. This HMAC signature will be sent with the webhook as X-Uber-Signature header field. Python Example
digester = hmac.new(client_secret, webhook_body, hashlib.sha256)
return digester.hexdigest()
Supplier companies can similarly generate this value on their side and compare both signatures. If the signatures don’t match, the API call can be discarded.