Uber Developers

Webhook Setup and Signing Key Rotation

The Developer Dashboard is a portal for third-party (3P) users to create applications and integrate with Uber services. This guide covers how to configure webhooks for your application and how to rotate your webhook signing key without downtime.

¶ Terminologies

Term	Description
Developer Dashboard	A portal for third-party (3P) users to create applications and integrate with Uber services.
Webhooks	There are some cases where it is useful for your server to be notified of changes in a resource rather than requesting that state from the API directly. Use webhooks to track these state changes.
Primary Webhook	The main webhook for an application, with a maximum of 1 allowed per app. Typically used when you want to configure only one webhook for your entire application.
Other-Webhooks	An application can have multiple webhooks. This is useful when an application is linked to several entities, such as multiple Uber Eats stores, and each store has a separate webhook cfg.
Webhook Developer UUID	A unique, immutable identifier for each webhook, acting as its primary key. This UUID is specific to Other Webhooks.
Webhook URL	This is the URL at which your server will receive POST requests about the changes in state of resources it may be interested in.
Signing Key	A shared key between Uber and the 3P application, used by Uber to create a signed header for secure communication.
Secondary Signing Key	A secondary shared key, used for creating signed headers and facilitating secure rotation of the signing keys between Uber and the 3P app.

All these parameters must be provided by third-party users. For specific uber-business, follow the relevant developer docs.

¶ How to configure a webhook for a 3P Application

Create an application on the Developer Dashboard.
There you will see an option to configure webhooks. For each webhook, follow these steps:
- Configure a primary-webhook or other-webhooks based on your business needs. If you want multiple webhooks configured for an application, use other-webhooks.
- Add a random webhook developer UUID (should be unique for each webhook).
- Add a webhook URL — use different URLs for each webhook.
- Add a signing key (should be stored securely at your end).
- (Optional) Add a secondary signing key (used during a signing key rotation procedure, and should be removed after the rotation completes).

¶ Webhook 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 hmac of the webhook message payload, computed using the application signing key.
`X-Uber-Signature-New`	SHA256 hmac of the webhook message payload, computed using the application secondary signing key.

¶ Webhook Security

Signed headers (X-Uber-Signature / X-Uber-Signature-New) are sent with every webhook request, ensuring the authenticity and integrity of the incoming webhook request. The value of these headers is the SHA256 hmac of the webhook message payload, computed using the application signing/secondary signing key.

X-Uber-Signature

digester = hmac.new(signing_key, webhook_message_payload, hashlib.sha256)
return digester.hexdigest()

X-Uber-Signature-New

digester = hmac.new(secondary_signing_key, webhook_message_payload, hashlib.sha256)
return digester.hexdigest()

¶ How to Verify Signing Headers at Your (3P) Server

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

The hmac for each header (X-Uber-Signature and X-Uber-Signature-New) should be computed using the same method described above.
Compare the hmac from the incoming webhook request with your computed hmac for each header.

¶ Rotation of Signing Key

The 3P adds a new signing key (s2) as the secondary key from the Developer Dashboard UI.
Uber’s system now has two signing keys, s1 and s2.
s1 will always be sent in X-Uber-Signature, and s2 will always be sent in X-Uber-Signature-New, since order is preserved.
The 3P should implement dual-read code for validating the signature.

Sample dual-read code that a 3P can implement:

signing_key = s1

verifySignature(payload)
{
    expectedHash = hash(signing_key + payload)
    actualHash = headers.GetValue("x-uber-signature")
    actualHashSecondary = headers.GetValue("x-uber-signature-new")

    if (expectedHash == actualHash) return true  -> pass
    else if (expectedHash == actualHashSecondary) return true

    return false
}

Migrate to the secondary signing key — the new code will look like the following:

signing_key = s2

verifySignature(payload)
{
    expectedHash = hash(signing_key + payload)
    actualHash = headers.GetValue("x-uber-signature")
    actualHashSecondary = headers.GetValue("x-uber-signature-new")

    if (expectedHash == actualHash) return true
    else if (expectedHash == actualHashSecondary) return true  -> pass

    return false
}

The 3P deletes s1 from the Developer Dashboard UI.
Uber will then start sending s2 in X-Uber-Signature, since there is now a single signing key in the system.

signing_key = s2

verifySignature(payload)
{
    expectedHash = hash(signing_key + payload)
    actualHash = headers.GetValue("x-uber-signature")
    actualHashSecondary = headers.GetValue("x-uber-signature-new")

    if (expectedHash == actualHash) return true  -> pass
    else if (expectedHash == actualHashSecondary) return true

    return false
}