Webhookについて

Webhookについて

JTB BÓKUNはWebhook経由でほかのシステムとのデータ連携が可能です。本記事では、JTB BÓKUNにおけるWebhookの設定方法について説明します。

Webhookを使用することで、特定のイベント（新規予約の作成、予約の更新、予約のキャンセル）が発生した際にリアルタイムで通知を受け取ることができます。

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データが含まれます。具体的な内容はイベントの種類によって異なります。詳細は以下の各イベントをご参照ください。

各イベント詳細

1．新規予約の作成

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

x-bokun-topic: bookings/create
x-bokun-booking-id: Qm9va2luZzozNzY0OA

 

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

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

2．予約の更新

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

x-bokun-topic: bookings/update
x-bokun-booking-id: Qm9va2luZzozNzY0OA

 

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

x-bokun-experiencebooking-id: RXhwZXJpZW5jZUJvb2tpbmc6OTQ2MTg

 

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

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

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

 

3．予約のキャンセル

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

x-bokun-topic: bookings/cancel
x-bokun-booking-id: Qm9va2luZzozNzY0OA

 

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

x-bokun-experiencebooking-id: RXhwZXJpZW5jZUJvb2tpbmc6OTQ2MTg

 

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

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

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

Webhookの設定方法

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

2．画面右上の「追加する」をクリックします。

3．「HTTP予約通知」を選択します。

4．統合設定の編集画面にて以下の内容を設定し、保存します。

• タイトル（必須）: この統合設定のタイトルです。例：Zapier連携。このタイトルは外部に表示されません。
• 詳細（オプション）: この連携内容の詳細記載欄です。
• アクティブ（必須）: この設定を有効化にするためのチェックボックスです。
• フラグ（オプション）: データを並べ替えたり、さらに変更を加えるための高度な機能。
• URL （必須※重要）: データの受信URLを貼り付けます。
• データ形式（必須）: データのフォーマットを選択します。ここではJSONを例に設定します。
• クエリパラメータ（オプション）: データを変更する高度な機能。
• 予約が確定したら通知する: 予約が作成された場合、JTB BÓKUNからデータを送信します。
• 予約が更新されたら通知する: 予約記録が変更された場合、JTB BÓKUNからデータを送信します。
• 予約がキャンセルされたら通知する: 予約記録がキャンセルされた場合、JTB BÓKUNからデータを送信します。