Webhookについて

Webhookについて

Webhook（ウェブフック）とは、JTB BÓKUNを他の外部システムと接続する連携機能です。残席数（在庫）のアップデートや新規予約の作成など、システム内で特定のイベントが発生した際に、リアルタイムで自動的にHTTPS通知を外部システムへ送信します。

Webhookを使って何ができますか

• お使いの外部システムとの連携
  会計ソフト、財務システム、カレンダーアプリなどの外部システムへ情報を直接同期。データ手入力の手間や時間を大幅に削減できます。

• アップデート情報をリアルタイムで自動送信
  商品情報の変更や残席（在庫）の変動がリアルタイムで自動通知されるため、システム間の情報不一致や手作業によるミスを防ぎます。

• Zapier連携による業務自動化
  業務自動化ツール「Zapier」を活用することで、さらに多くの外部アプリやシステムとJTB BÓKUNを接続し、日々のルーティンワークを自動化できます。Zapierとの連携方法はこちらの記事をご参照ください。

Webhookを利用する手順

1．HTTPSエンドポイントの準備

• 有効なSSL証明書を持つHTTPSのWebhookアドレスを用意します。
• このエンドポイントは、後述する方法でイベント通知を正しく処理できる必要があります。

2．Webhookの検証機能の実装

• JTB BÓKUNからのWebhookリクエストであることを確認するための検証機能を実装します。

3．ペイロードの処理

• JSONオブジェクトとして送信されるWebhookイベントのデータを処理できるようにします。
• イベントの種類によってペイロードの内容と構造が異なることに注意してください。

4．Webhookの受信設定

• Webhook URLを登録すると、該当イベントが発生するたびにJTB BÓKUNからHTTP POSTリクエストが送信されます。
• サーバーがHTTPSと有効なSSL証明書をサポートするよう正しく設定されていることを確認してください。

5．Webhookへの応答

• Webhookがデータを受信したことを示すため、200 OKレスポンスを送信します。

6．署名の検証（※Bókun APPとして構築する場合のみ必要、ほとんどの場合は不要）

• 各Webhookリクエストに含まれるbase64エンコードされたX-Bokun-HMACヘッダーを使用して、リクエストの真正性を確認します。
• アプリのシークレットキーを使用してHMAC-SHA256ダイジェストを計算し、ヘッダーの値と比較します。

注意事項

• 200以外のレスポンス（3XXリダイレクトコードを含む）は、Webhookの受信に失敗したとみなされます。
• JTB BÓKUNは各リクエストに対して5秒のタイムアウト期間を設けており、応答がない場合は数回再試行します。
• すべての再試行が失敗した場合、Webhook登録は自動的に削除されます。
• タイムアウトやエラーを避けるため、Webhookレスポンス送信後にアプリの処理を行うことを検討してください。
  
  

よくある質問

Q1: Webhookの検証に失敗した場合、どうすればよいですか？

A1: アプリのシークレットキーが正しいこと、およびHMAC-SHA256ハッシュ関数の実装が正確であることを確認してください。それでも問題が解決しない場合は、JTB BÓKUNサポートにお問い合わせください。

Q2: Webhookのペイロードにはどのような情報が含まれますか？

A2: ペイロードには、トリガーとなったイベントに関連するJSONデータが含まれます。具体的な内容はイベントの種類によって異なります。詳細は以下の各イベントをご参照ください。

予約関連のWebhookの各イベント

1．新規予約の作成

このイベントは、予約が確定（confirmed）のステータスで作成されたときに送信されます。

x-bokun-booking-idヘッダーは予約のユニークIDを提供します。その後、GraphQL APIを使用して詳細を取得できます。本文には以下の構造のJSONが含まれます：

{
  "timestamp": "2020-09-07T11:06:32.419",
  "bookingId": "Qm9va2luZzozNzY0OA"
}

2．予約の更新

このイベントは、予約またはその予約に含まれるいずれかの体験予約が更新されたときに送信されます。変更とは人数、追加オプション、日付、体験商品の変更を指します。また、顧客のステータスが到着済みやノーショーに変わった場合もトリガーされます。

場合によって、以下のような追加のヘッダーがあるかもしれません：

もし予約内の特定の体験予約に関連する変更がある場合、x-bokun-experiencebooking-idヘッダーはその体験予約を識別します。

本文には以下の構造のJSONが含まれます：

3．予約のキャンセル

このイベントは、予約またはその予約に含まれるいずれかの体験予約がキャンセルされたときに送信されます。リクエスト予約が拒否された場合はトリガーされません。

場合によって、以下のような追加のヘッダーがあるかもしれません：

もし予約内の複数の体験予約のうちの1つがキャンセルされた場合、x-bokun-experiencebooking-idヘッダーはその体験予約を識別します。それ以外の場合は、予約全体がキャンセルされたと考えることができます。

本文には以下の構造のJSONが含まれます：

{
   "timestamp": "2020-09-07T11:06:32.419",
   "bookingId": "Qm9va2luZzozNzY0OA",
   "experienceBookingId": "RXhwZXJpZW5jZUJvb2tpbmc6OTQ2MTg"
}

Webhookの設定方法

1．JTB BÓKUN管理画面＞設定＞他システムとの連携＞Webhooksをクリックします。

2．「Webhookを作成する」をクリックします。

3．「予約関連のWebhook」または「商品関連のWebhook」を選択して、「新しく作成する」をクリックします。

4．予約関連のWebhookの作成画面にて以下の内容を設定し、保存します。

• タイトル（必須）: このwebhookのタイトルです。例：Zapier連携。このタイトルは外部に表示されません。
• 詳細（オプション）: このWebhookは何をどのように連携するかを記載します。
• URL （必須※重要）: データの受信URLを貼り付けます。Webhookのペイロード（データ）は、このHTTPSエンドポイント宛てにPOSTリクエストで送信されます。
• 種類：「HTTP予約通知」または「HTTP商品予約通知」を選択します。
• データ形式（必須）: データのフォーマットを選択します。ここではJSONを例に設定します。
• クエリパラメータ（オプション）: データを変更する高度な機能。
• 予約関連のWebhook：トリガーとなるイベントを選択します。
  • 予約が確定したら通知する: 予約が作成された場合、JTB BÓKUNからデータを送信します。
  • 予約が更新されたら通知する: 予約記録が変更された場合、JTB BÓKUNからデータを送信します。
  • 予約がキャンセルされたら通知する: 予約記録がキャンセルされた場合、JTB BÓKUNからデータを送信します。

5．商品関連のWebhookの作成画面にて以下の内容を設定し、保存します。

• タイトル（必須）: このwebhookのタイトルです。例：商品更新通知。このタイトルは外部に表示されません。
• コールバックURL （必須※重要）: データの受信URLを貼り付けます。Webhookのペイロード（データ）は、このHTTPSエンドポイント宛てにPOSTリクエストで送信されます。
• 種類：「商品を更新」、「商品リストを更新」、「タグ構造の更新」または「商品の利用可能状況を更新する」のいずれかを選択します。