Webhook
Recustomer → マーチャント(通知)
返品の作成・更新、および配送ステータスの更新を、Recustomer からマーチャントのエンドポイントへ HTTP POST で通知します。
通知を受け取るには、管理画面の Webhook 設定で、イベント(返品作成・返品更新・配送ステータスの更新)とコールバック URL を組み合わせて登録します。Recustomer は、登録されたイベントのみを通知します。リクエスト本文にはイベントの種類が含まれないため、イベントの種類を区別する場合は、イベントごとに異なる URL を登録してください。
通知の仕様
- リクエスト本文は UTF-8 の JSON(Content-Type: application/json)です。User-Agent は Recustomer-Webhook/1.0 です
- 配信先は、HTTPS(TLS 1.2 以上)かつポート 443 の URL に限ります。社内ネットワークなど、インターネットから到達できない配信先には配信しません
- エンドポイントが 2xx を返した場合、配信は成功となります。レスポンス本文の内容は参照しないため、本文は空で問題ありません。3xx・4xx・5xx、タイムアウト、名前解決や接続のエラーは、配信の失敗として扱います。2xx を返した場合でも、レスポンス本文の途中で接続が切断された場合や、本文が Content-Length に満たない場合など、本文を最後まで受信できなかったときは失敗として扱います
- 接続の開始から 10 秒以内にレスポンスヘッダーを受信できない場合は、配信を中断して失敗として扱います。この 10 秒には、接続と TLS ハンドシェイクに要した時間も含みます。レスポンス本文の受信が 10 秒間停止した場合も、同様に中断します
- エンドポイントは、通知を受信したら速やかに 2xx を返してください。時間のかかる処理は、通知をキューやデータベースに保存して 2xx を返したあと、非同期で実行することを推奨します
- 通知の到着順序は保証しません。また、同じイベントが重複して配信される場合があります。処理済みの X-Recustomer-Event-Id をデータベースなどに記録し、記録済みの ID を持つ通知は処理をスキップしてください
失敗時の再送
配信に失敗した場合、Recustomer は同じ通知を自動的に再送します。再送までの待機時間は 2 分から始まり、再送のたびに 2 倍になります(指数バックオフ)。初回の配信を含めて 8 回すべて失敗した場合は、そのイベントの配信を終了します。現在、配信を終了したイベントを後から再送する仕組みはありません。配信を終了したイベントは「Webhook 配信ログ」で確認してください。
- 1 回目イベント発生時
- 2 分待機2 回目約 2 分後
- 4 分待機3 回目約 6 分後
- 8 分待機4 回目約 14 分後
- 16 分待機5 回目約 30 分後
- 32 分待機6 回目約 1 時間 2 分後
- 64 分待機7 回目約 2 時間 6 分後
- 128 分待機8 回目約 4 時間 14 分後
- 配信終了8 回目も失敗した場合
- いずれかの試行で 2xx を返すと、以降の再送は行いません
- 時刻は初回の配信を起点とした目安です。待機時間は前の試行が失敗してから数え始め、各試行の通信時間(最大で 10 秒程度)や、再送の処理が開始されるまでの時間が加わるため、実際の時刻は記載よりも遅くなる場合があります
- エンドポイントが一時的に停止していても、復旧後の再送で通知を受信できます。現在、最後の再送は初回の配信から約 4 時間 14 分以降に行われます
- 再送時も、リクエスト本文と X-Recustomer-Event-Id は変わりません。署名は配信のたびに、その時刻で生成し直します
- 配信結果は、管理画面の左メニュー「アナリティクスβ」の「Webhook 配信ログ」で確認できます。イベントごとに、配信日時・試行回数・HTTP ステータス・エラー内容・送信した本文が表示されます
リダイレクト(3xx)の扱い
Recustomer はリダイレクトに追従しません。3xx のレスポンスは配信の失敗として扱い、ほかの失敗と同様に再送します。エンドポイントが常に 3xx を返す場合は、8 回すべてが失敗となり、配信を終了します。
コールバック URL には、リダイレクトが発生しない最終的な URL を登録してください。「Webhook 配信ログ」の HTTP ステータスが 3xx となっている場合は、curl -i -X POST <コールバック URL> でレスポンスの Location ヘッダーを確認し、リダイレクト先の URL を登録し直してください。次のような URL では、リダイレクトが発生することがあります。
- ホスト名の www の有無やドメインが、エンドポイントの正しい URL と異なる
- パス末尾の / の有無が、エンドポイントの正しい URL と異なる
- エンドポイントが認証を要求し、ログイン画面へリダイレクトする
- Google Apps Script のウェブアプリで、ContentService を使って結果を返している。Apps Script は結果を 302 で別の URL から返すため、スクリプトの処理が完了していても、Recustomer は配信の失敗として扱い、同じ通知を再送します。2xx を直接返せるエンドポイントを用意してください
リダイレクトに追従しない理由は、次のとおりです。
- 3xx は、エンドポイントが通知を受信したことを示しません。受信を示すのは 2xx のみです
- 301・302・303 に追従すると、POST が GET に変わり、リクエスト本文が送信されない場合があります。リダイレクト先のログイン画面が 200 を返すと、通知が届いていないにもかかわらず、配信が成功したように見えてしまいます
- リクエスト本文には購入者の個人情報が含まれます。本文と署名は、登録された URL にのみ送信します
署名の検証
Recustomer は通知ごとにリクエスト本文の署名を生成し、X-Recustomer-Signature-256-V2 ヘッダーで送信します。署名した時刻(Unix 時刻・秒)は X-Recustomer-Signature-256-V2-Timestamp-Epoch ヘッダーで送信します。エンドポイントでは、本文を JSON として解析する前に、署名を検証してください。
- 管理画面の Webhook 設定で、登録した Webhook の「シークレットを表示」から署名シークレットを確認します
- X-Recustomer-Signature-256-V2-Timestamp-Epoch の値、
.、受信した本文(JSON として解析する前のバイト列)をこの順に連結し、署名シークレットを鍵として HMAC-SHA256 を計算します。結果は小文字の 16 進文字列とします(接頭辞は付けません) - 手順 2 の値と X-Recustomer-Signature-256-V2 ヘッダーの値を、定数時間で比較します。一致しない場合、または署名した時刻が現在時刻から 5 分を超えてずれている場合は、通知を処理しないでください
署名シークレットは Webhook(イベントと URL の組み合わせ)ごとに発行され、「シークレットを再発行」で再発行できます。現在、再発行より前に発生したイベントの再送には、再発行前のシークレットで署名します。再送は初回の配信から 4 時間 14 分以上続く場合があるため、再発行後 5 時間程度は、再発行前のシークレットでも検証できるようにしてください。再発行前のシークレットを直ちに無効にすると、その間に再送された通知はエンドポイントで拒否され、そのイベントの配信は終了します。
署名シークレットは 64 文字の 16 進文字列です。パスワードと同様に厳重に管理し、ソースコードやリポジトリには含めず、環境変数やシークレット管理サービスに保管してください。漏洩のおそれがある場合は、「シークレットを再発行」で再発行してください。
Rails・Django など、POST リクエストに CSRF 対策の検証を適用するフレームワークでは、エンドポイントのルートを CSRF の検証対象から除外してください。Webhook の通知は CSRF トークンを持たず、署名によって検証します。
各 Webhook のページの「エンドポイントの実装例」に、上記の手順を実装したコードを掲載しています。