Webhook

Webhook β版について

Webhookはβ版として公開中です。
正式版に向けて、お客様からのフィードバックを参考に改善を進めていきます。ぜひご意見・ご要望をお寄せください。

β版のご利用にあたって

β版は開発中の機能のため、以下の点にご注意ください。
・仕様変更の可能性：正式版公開時に仕様が大きく変更になる場合があります。
・サポートの制限：β版に関するサポートは限定的となる場合があります。

Webhookについて

予約データの登録・キャンセルなどのイベントを、管理画面で設定した通知タイミングでリアルタイムにWebhook URLに送信します。

通知タイミングとアクション名

アクション名は送信データの「action」に設定されます。
※予約更新は、内容が変更されたかに関係なく、更新操作が行われた場合に送信します。

通知タイミング	アクション名
予約登録	reservation_insert
予約更新	reservation_update
キャンセル	reservation_cancel
仮予約承認	reservation_unfixed_accept
仮予約拒否	reservation_unfixed_reject
完了	reservation_finish

 

Webhook通知の対象外となるケース

予約ブロック
・複数件処理された中に予約ブロックが含まれる場合、予約ブロックのデータは送信されません。
・通常予約1件と予約ブロック3件の予約データを同時にステータス変更した場合、通常予約の1件のみが送信され、送信ログには通常予約の予約番号が表示されます。
・通常予約が複数件ある場合、全体の件数から予約ブロックの件数を引いた件数が送信ログの件数に表示されます。

『基本設定>総合管理>一括処理』
・完了処理
・キャンセル処理

強制削除によるキャンセル
以下のデータを強制削除する場合、予約データも同時に削除されます。この場合、Webhookは通知されません。
・メインメニュー
・サブメニュー
・会員

複数件の予約番号が一度のリクエストで送信される可能性のある処理

以下の処理において、一度の操作で複数件が対象となった場合、一度のリクエストで予約番号が複数送信されます。

予約登録
・予約アップロード
・抽選データを"承認"（※時間タイプ）

キャンセル
・予約一覧で"キャンセル"
・スケジュール詳細で"キャンセル"（※スクールタイプ）
・受付状況詳細で"キャンセル"（※イベントタイプ）

仮予約承認
・予約一覧で"承認"

仮予約拒否
・予約一覧で"拒否"

完了
・予約一覧で"完了"
・スケジュール詳細で"完了"（※スクールタイプ）
・受付状況詳細で"完了"（※イベントタイプ）
・自動完了
・管理カレンダーで"一括完了"（※時間タイプ、会議室タイプ）

リクエスト

イベント通知は、設定した「Webhook URL」に POST リクエストをすることによって行われます。 POST リクエストの構造は以下の通りです。

リクエストヘッダー

フィールド名	値
authorization	設定画面の「認証キー」
content-type	application/json

 

リクエストボディ

JSON オブジェクト
全通知タイミング共通

フィールド名	型	説明
action	文字列	アクション名
data	配列	各配列内に reservation_id をキーに予約番号（数値）が設定

 

サンプル

リクエストヘッダー

共通

• authorization: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  content-type: "application/json"

リクエストボディ

一件のみ

• {
     "action": "reservation_update",
     "data": [
      {
       "reservation_id": 13014
      }
     ]
  }

複数件

• {
     "action": "reservation_finish",
     "data": [
      {
        "reservation_id": 12960
      },
      {
        "reservation_id": 12929
      },
      {
       "reservation_id": 12977
      },
      {
       "reservation_id": 12946
      }
     ]
  }

レスポンス

・リクエストに対しては、常にHTTPステータスコード「200」を返してください。
・レスポンスボディは空で返してください。
・リクエストには5秒以内に応答してください。応答時間が5秒を超えた場合、「失敗」として処理されます。
・Webhook の再送は行われません。

認証キーの検証

リクエストの送信元が ChoiceRESERVE であることを確認するため、リクエストごとに受信サーバー側で、 認証キーが一致しているか確認を行ってください。

送信ログが失敗となる場合

様々な原因が考えられますが、主な原因は以下のとおりです。
なお、戻り値のHTTPステータスコードはログとして保持されないため、「200」以外のHTTPステータスコードが返された場合は、すべて「失敗」となります。

レスポンスのステータスコードが「200」以外で返された場合

・受信サーバー側でエラーが発生し、500番台のHTTPステータスコードが返された。
・リダイレクトが発生し、300番台のHTTPステータスコードが返された。リダイレクトは一定回数まで追跡されますが、追跡回数を超えると「失敗」となります。
・短時間にWebhookの送信が大量に発生し、受信サーバー側がアクセスを拒否した。
・200番台のHTTPステータスコードであっても、「201」などが返された場合は「失敗」となります。

URL が存在しない場合

HTTPステータスコード「404」が返された。

URL に、IP制限や認証が必要でアクセスできない場合

HTTPステータスコード「401」が返された。
Basic認証や特定のヘッダーを必要とするURLには送信できません。

レスポンスが5秒以内に返されなかった場合

予約CSVアップロード、管理画面での一括完了処理、自動完了処理など、大量の予約番号が送信される場合、各予約番号の処理後にレスポンスを返している場合は、非同期処理などを利用し、レスポンスを返してから別途処理を行ってください。

サンプルコード

PHP のサンプルコードです。

• // 実際には認証キーは直接ファイルに記載しないでください
  $auth_key = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
  
  // POSTパラメータを取得
  $temp_post_param = file_get_contents('php://input');
  
  $auth = '';
  $flg_error = false;
  
  // ヘッダーを取得
  $header = apache_request_headers();
  
  if (is_array($header)) {
       $header = array_change_key_case($header, CASE_LOWER); // キーを小文字に
       if (isset($header['authorization'])) {
           $auth = trim($header['authorization']);
           // 認証キーをチェック
           if (strcmp($auth, $auth_key) !== 0) {
               // 認証キーが一致しない場合はエラー
               $flg_error = true;
           }
       } else {
           // 認証キーが取得できない場合はエラー
           $flg_error = true;
       }
  } else {
       // ヘッダーが取得できない場合はエラー
       $flg_error = true;
  }
  
  if ($flg_error) {
       // エラーがある場合は処理終了（レスポンスコードは常に 200 を返却してください）
       header("{$_SERVER['SERVER_PROTOCOL']} 200 OK");
       exit;
  }
  
  // POSTパラメータが取得できた場合
  if ($temp_post_param !== false) {
       // JSONデコード
       $ar_json_param = json_decode($temp_post_param, true);
       if ($ar_json_param !== null) {
           // パラメータが取得できた場合は処理を実行
           $action = $ar_json_param['action'];
           $ar_data = $ar_json_param['data'];
           switch ($action) {
               case 'reservation_insert':
                   // 予約登録処理
                   foreach ($ar_data as $value) {
                           $reservation_id = $value['reservation_id'];
                           // 予約番号に対する処理を実行
                   }
                   break;
               case 'reservation_update':
                   // 予約更新処理
                   break;
               case 'reservation_cancel':
                   // キャンセル処理
                   break;
               case 'reservation_unfixed_accept':
                   // 仮予約承認処理
                   break;
               case 'reservation_unfixed_reject':
                   // 仮予約拒否処理
                   break;
               case 'reservation_finish':
                   // 予約完了処理
                   break;
               default:
                   // 未定義のアクション
                   break;
           }
       }
  }
  
  // レスポンス 200を返却する
  header("{$_SERVER['SERVER_PROTOCOL']} 200 OK");
  
  // 返却内容は無し
  exit;