Webhooks are an important service that enable near realtime updates for every Voucher program created through the API to be pushed to a web URL defined in your application’s settings. The Developer App settings page can be found below by modifying the URL below with your applications CLIENT_ID.

https://developer.uber.com/dashboard/app/<CLIENT_ID>/settings

¶ Introduction

Webhooks are a communication standard that makes it easy to get push notifications as an event happens. Unlike APIs where you call an endpoint for data, you provide a callback URL where you will be notified as events happen. For example, when an Uber Voucher is created through the API, Uber can send information through HTTP POST to your callback URL. Your callback URL can then execute code based on the POST.

Webhooks can be sent more than once and the delivery is not guaranteed to be in order. To defend against this behavior, a resource_href is provided in the body of the POST to get the most update-to-date information on each resource.

¶ Configure your Webhook

To enable webhooks, log in to the developer dashboard and go the Settings tab for your app. Under the Ride Requests section, add your webhook URL and click save. The Developer App settings page can also be found below by modifying the URL below with your applications CLIENT_ID.

https://developer.uber.com/dashboard/app/<CLIENT_ID>/settings

You can enter any URL you’d like to have events sent to, but this should be a dedicated https page on your server.

¶ POST Parameters

Webhooks sent from Uber’s servers will follow a standard format so that your application can easily understand what action it may want to take based on the contents of the payload. Below are the POST parameters that can be expected with each POST request received.

¶ Resource

Name	Type	Description
organization_id	string	Campaign manager organization UUID
event_type	string	The type of event that occurred
campaign_organization_id	string	Campaign owner Organization UUID. For First partners using organizations.voucher_programs scope, this UUID will be same as organization_id
voucher_program_id	string	The unique identifier when a voucher program is created
usage_voucher_claim_count	string	Indicates how many vouchers have been claimed for this voucher program so far
usage_trip_count	string	Indicates how many trips happened in this voucher program so far
usage_amount	string	The total amount of money that has been charged in this voucher program so far (Note: This is best effort, as updates to this value may be delayed.)
usage_amount_currency	string	The currency code of the usage amount (in iso 4217 format)
code_uuid	string	The unique identifier for the voucher redemption code
code_text	string	The voucher redemption code
is_disabled	string	Indicates if this voucher program is active or not, will be set to true if the cancel voucher program endpoint is called
resource_href	string	The URL of the resource being referenced. This URL can be called with your App’s bearer token to retrieve the full payload
webhook_meta	object	The object containing additional information that is specific to the webhook event
webhook_meta.client_id	string	Subscriber’s client_id
webhook_meta.webhook_config_id	string	Webhook config id
webhook_meta.webhook_msg_timestamp	int64	Subscriber’s client_id
webhook_meta.webhook_msg_uuid	string	The webhook’s unique uuid

¶ Event Types

Once you’ve been granted access to your organization’s data, you will begin receiving webhook events for all vouchers created through the API. We currently have six event_type values outlined below.

Event type	Description
voucher_program_code_claimed	Sent when a voucher code is claimed
voucher_program_code_redeemed	Sent when a voucher code is redeemed for a trip or a meal
voucher_program_code_distributed	Sent when a voucher code distribution request is completed
voucher_program_updated	Sent when voucher program fields are updated: name, duration, memo, number of vouchers, coverage type, discount type
voucher_program_completed	Sent when a voucher program is completed/canceled
voucher_program_created	Sent when a new voucher program is created
voucher_program_activated	Sent when a voucher program becomes active

¶ Example Request

Below are a few examples of status updates that are sent as a Voucher program progresses. Note: these are just a few examples and do not cover all possible updates that can be sent.

{
    "organization_id": "<campaign manager organization uuid>",
    "event_type": "voucher_program_code_claimed",
    "campaign_organization_id": "<campaign owner organization uuid>",
    "voucher_program_id": "<campaign uuid>",
    "usage_voucher_claim_count": "1",
    "usage_amount": "100.0",
    "usage_amount_currency": "USD",
    "code_uuid": "<code uuid>",
    "code_text": "<code text>",
    "resource_href": "https://api.uber.com/v1/organizations/<organization_id>/voucher-programs/<voucher_program_id>",
    "webhook_meta": {
       "client_id": "<client_id>",
       "webhook_config_id": "voucher_program_code_claimed",
       "webhook_msg_timestamp": 1613595672,
       "webhook_msg_uuid": "<unique msg uuid>"
    }
}

{
   "organization_id": "<campaign manager organization uuid>",
   "event_type": "voucher_program_code_redeemed",
   "campaign_organization_id": "<campaign owner organization uuid>",
   "voucher_program_id": "<campaign uuid>",
   "usage_trip_count": "2",
   "usage_amount": "100.0",
   "usage_amount_currency": "USD",
   "code_uuid": "<code uuid>",
   "code_text": "<code text>",
   "resource_href":  "https://api.uber.com/v1/organizations/<organization_id>/voucher-programs/<voucher_program_id>",
    "webhook_meta": {
       "client_id": "<client_id>",
       "webhook_config_id": "voucher_program_code_redeemed",
       "webhook_msg_timestamp": 1613595672,
       "webhook_msg_uuid": "<unique msg uuid>"
    }
}

{
   "organization_id": "<campaign manager organization uuid>",
   "event_type": "voucher_program_code_distributed",
   "campaign_organization_id": "<campaign owner organization uuid>",
   "voucher_program_id": "<campaign uuid>",
   "code_distribution_results": [
      {
         "recipient_name": "<recipient name>",
         "recipient_email": "<recipient email address>",
         "success": "<success flag>",
         "code_uuid": "<code uuid>",
         "code_text": "<code text>"
      },{
         "…"
      }
   ],
   "resource_href": "https://api.uber.com/v1/organizations/<organization_id>/voucher-programs/<voucher_program_id>",
   "webhook_meta": {
      "client_id": "<client_id>",
      "webhook_config_id": "voucher_program_code_distributed",
      "webhook_msg_timestamp": 1613595672,
      "webhook_msg_uuid": "<unique msg uuid>"
   }
}

{
   "organization_id": "<campaign manager organization uuid>",
   "event_type": "voucher_program_updated",
   "campaign_organization_id": "<campaign owner organization uuid>",
   "voucher_program_id": "<campaign uuid>",
   "resource_href":  "https://api.uber.com/v1/organizations/<organization_id>/voucher-programs/<voucher_program_id>",
   "webhook_meta": {
       "client_id": "<client_id>",
       "webhook_config_id": "voucher_program_updated",
       "webhook_msg_timestamp": 1613595672,
       "webhook_msg_uuid": "<unique msg uuid>"
   }
}

{
  "organization_id": "<campaign manager organization uuid>",
  "event_type": "voucher_program_created",
  "campaign_organization_id": "<campaign owner organization uuid>",
  "voucher_program_id": "<campaign uuid>",
  "resource_href": "https://api.uber.com/v1/organizations/<organization_id>/voucher-programs/<voucher_program_id>",
  "webhook_meta": {
       "client_id": "<client_id>",
       "webhook_config_id": "voucher_program_created",
       "webhook_msg_timestamp": 1613595672,
       "webhook_msg_uuid": "<unique msg uuid>"
  }
}

{
  "organization_id": "<campaign manager organization uuid>",
  "event_type": "voucher_program_completed",
  "campaign_organization_id": "<campaign owner organization uuid>",
  "voucher_program_id": "<campaign uuid>",
  "is_disabled": "true",
  "resource_href": "https://api.uber.com/v1/organizations/<organization_id>/voucher-programs/<voucher_program_id>",
  "webhook_meta": {
       "client_id": "<client_id>",
       "webhook_config_id": "voucher_program_completed",
       "webhook_msg_timestamp": 1613595672,
       "webhook_msg_uuid": "<unique msg uuid>"
  }
}

{
  "organization_id": "<campaign manager organization uuid>",
  "event_type": "voucher_program_activated",
  "campaign_organization_id": "<campaign owner organization uuid>",
  "voucher_program_id": "<campaign uuid>",
  "resource_href": "https://api.uber.com/v1/organizations/<organization_id>/voucher-programs/<voucher_program_id>",
  "webhook_meta": {
       "client_id": "<client_id>",
       "webhook_config_id": "voucher_program_activated",
       "webhook_msg_timestamp": 1613595672,
       "webhook_msg_uuid": "<unique msg uuid>"
  }
}

¶ Security

Webhook messages are signed so that your app can verify that the sender is Uber. Webhooks requests contain an X-Uber-Signature header. The value of this field is a hexadecimal HMAC signature of the webhook HTTP request body, using signing key of primary webhook url as a key and SHA256 as the hash function.

Python Example

digester = hmac.new(client_secret, webhook_body, hashlib.sha256)
return digester.hexdigest()

¶ Headers

The Uber API will insert specialized headers for all requests made to your webhook URL to help your application utilize them appropriately.

Header	Description
X-Environment	Indicates if this request is coming from the production or sandbox API.
X-Uber-Signature	SHA256 hash of the request body, using the client secret as the key.

¶ Retry Attempts

If for some reason the Uber API cannot reach the webhook URL you specified either due to networking issues or application issues on your end, the webhooks service will retry to make a request.

We have implemented an exponential back-off algorithm with a back-off multiplier of 1 seconds which will make up to 3 attempts. Webhook requests will timeout after 10 seconds for each request / retry. (i.e. - The request going out to a remote server will be timed-out after 10 seconds if no response is received) Timeouts and HTTP 500/502/503/504 responses will trigger a retry.