Webhook を通じてアプリケーションに通知することにより、Uber Direct では配達に関するリアルタイムのアップデートをより簡単に利用できます。このガイドでは、これらの通知を設定、受信、認証、処理する詳しい手順を説明します。

¶ Webhook エンドポイントを設定する

Webhook 通知は、指定したインターネットエンドポイントへの POST リクエストとして Uber Direct から送信されます。エンドポイントを有効にしてリッスンを開始したら、Uber Direct ダッシュボード（direct.uber.com）からエンドポイント URL を追加できます。

Webhook の受信を希望する場合は、Uber に 1 つ以上の URL を提供してください。

1. 左側の [開発者] タブ、[Webhooks] タブの順にクリックします。
   
2. [Webhook を作成する] をクリックします。
   このステップでは、URL ごとに適切なタイプの Webhook を選択できます。event.delivery_status と event.courier_update に関する詳しい説明は、以下のリソースを参照してください。
   • event.delivery_status の説明
   • event.courier_update の説明
   • event.refund の説明
3. [Webhook URL] にサービスエンドポイントを入力します。
   重要：セキュリティ上の理由から、Uber からの HTTPS リクエストを受け入れるように、自身のウェブアプリケーションを設定する必要があります。
4. この URL に送信する Webhook を選択します。すべてのタイプの Webhook に 1 つの URL を使用することも、それぞれに別々の URL を使用することもできます。
5. [保存] をクリックします。

¶ Webhook を認証する

Webhook を作成すると、専用の Webhook 署名キーが提供されます。この秘密キーはアプリケーションと Uber の間で共有される秘密キーであり、Webhook エンドポイントの受信メッセージの真正性と完全性を確保します。

特定の Webhook の署名キーを取得するには、それぞれの Webhook エントリに移動し、3 つの点の記号をクリックします。ドロップダウンメニューから [編集] オプションを選択します。

Webhook の POST メッセージに送信されるエンドポイントには、ヘッダー x-uber-signature が含まれます。これは、署名キーを使用して生成されたメッセージペイロードの SHA-256 ハッシュです。以下の手順を実行すると、Webhook メッセージを確認できます。

1. 指定した署名キーを使ってメッセージの SHA-256 ハッシュを計算します。使用するプログラミング言語の標準の HMAC 関数を使用することをお勧めします。
2. x-uber-signature ヘッダーにあるハッシュ値と比較してチェックサムを検証します。チェックサムがハッシュ値と一致すれば、意図したとおりにメッセージの処理を続行します。一致しない場合は、無視します。

処理を進める前にチェックサムの有効性を確認することによって、メッセージの完全性と真正性を確保することがきわめて重要です。

以下は、署名キーとメッセージペイロードが与えられたときの x-uber-signature の値を計算する Python スクリプトの例です。

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'

重要

1. Delivery Status Webhook と Courier Update Webhook では、上述の確認に x-uber-signature または x-postmates-signature を使用できます。ただし、Refund Webhook の場合は、x-uber-signature を使用して確認してください。
2. JSON/文字列解析では、意図しない文字変換を回避します。
   Webhook の本文を処理する際には、「\uXXXX」のような Unicode 文字のエスケープシーケンスが含まれている可能性があることに注意してください。解析メソッドでは、元の未加工のフォーマットが維持されるようにします。解析関数によっては、エスケープシーケンスを意図せずにそれぞれの文字に変換してしまうことがあります（例：\u0026 が &）。予期せぬ変換を防ぐため、元の形式を保持する解析方法またはライブラリを選択します。エスケープシーケンスを含む入力をテストすれば、解析関数の完全性を確認できます。

¶ 再試行ロジック

Uber に 500、502、503、504 のステータスコードが届くか、タイムアウト、またはなんらかのネットワークエラーが発生した場合、Webhook のイベントが再試行されます。最初の再試行の送信は、最初のイベントから 10 秒後に行われます。その後のイベントの再送信は、指数関数的後退アルゴリズムに基づいて行われます。10 秒後に行われた再試行を起点として 30 秒後、60 秒後、120 秒後のように再送信が行われ、応答が届くまで、または合計 3 回イベントを送信するまで続けられます。

別のステータスコードのために Webhook が受信されない場合は、Get Delivery エンドポイントを使用して配達のデータを取得することをお勧めします。