はじめに
Webhook API サービス連携により、TimeRexで特定のイベントが発生したときに、指定したURLにPOSTすることができます。
主な使用例は、こちらです。
- CRMに予約の詳細を追加する
- SaaSツールに予約の詳細を追加する
- 独自サービスと統合する
ご利用条件
Webhook APIは、プレミアムプランのすべてのユーザーが利用できます。
設定
Webhookは、以下のページから設定できます。
アカウント設定→サービス連携
チーム設定→サービス連携
Webhook URLについて
Webhookを設定する前に、TimeRexからのリクエストを受信できるhttpsエンドポイント(以下、Webhook URL)を準備する必要があります。
Webhook URLは、以下の点に注意してください。
- HTTPSのURLのみ使用可能
- 有効なSSL証明書が設定されている必要がある
- 自己署名証明書は無効
- localhostのURLは使用不可
- SSL通信ではポート443のみ使用可能
- IPアドレスは使用不可
以下は、有効なWebhook URLの例です。
- https://yourserver.com/callback
- https://api.yourserver.com/callback
- https://api.yourserver.com:443
以下は、無効なWebhook URLの例です。
- http://yourserver.com/callback
- http://localhost/
- https://api.yourserver.com:8000
Webhook URLが準備できたら、サービス連携ページからTimeRexにリンクできます。
※ 次のようなサービスを利用して、テスト用のWebhook URLを生成できます。
Webhookを設定すると、セキュリティトークンが生成されます。このセキュリティトークンを使用して、リクエストがTimeRexから送信されたものか検証することを、強く推奨します。
リクエスト
TimeRex Webhook APIは、POSTメソッドでリクエストします。
リクエストヘッダ
TimeRexからのWebhookリクエストヘッダには、必ず以下のキーが含まれます。
{ "content-type": "application/json", "accept": "application/json", "user-agent": "TimeRex API v", "authorization": "" }
Authorizationヘッダを使用して、セキュリティトークンがTimeRexアカウントのトークンと一致するか確認することを、推奨します。一致しない場合は、リクエストを破棄してください。
イベントタイプ
現在、TimeRex Webhookにより送信されるイベントタイプは、以下の2種類です。
- event_confirmed
- event_cancelled
詳細は、リクエストボディセクションで説明します。
リクエストボディ
リクエストボディはJSONオブジェクトに基づいており、イベントタイプによって異なります。リクエストボディとフォーマットは以下です。
event_confirmed
TimeRexで予約が確定されたときに生成されるWebhookリクエストです。次のリクエストボディが含まれています。
例
{ "webhook_type": "event_confirmed", "calendar_url_path": "215aa110", "team_url_path": "mixtend_e6ed", "calendar_url": "https://timerex.net/s/mixtend_e6ed/215aa110", "event": { "id": "1981d18a994f60e7bcc2", "status": 1, "duration": 60, "pre_travel_time": 0, "post_travel_time": 0, "start_datetime": "2020-08-26T09:00:00+00:00", "end_datetime": "2020-08-26T10:00:00+00:00", "local_start_datetime": "2020-08-26T18:00:00+09:00", "local_end_datetime": "2020-08-26T19:00:00+09:00", "calendar_timezone": "Asia/Tokyo", "guest_locale": "ja", "created_at": "2020-08-20T02:22:40+00:00", "host_cancel_url": "https://timerex.net/schedule/host_cancel/1981d18a994f60e7bcc2", "guest_cancel_url": "https://timerex.net/schedule/cancel/1981d18a994f60e7bcc2", "online_meeting_provider": "zoom", "zoom_meeting": { "meeting_id": 83736482957, "join_url": "https://us02web.zoom.us/j/83736482957?pwd=TXQ0Kzh4NUQvQ2RGZHFDOEwxVW9Vdz09", "password": "035211", "host": { "name": "Mixtend Demo", "email": "demo@mixtend.com" } }, "hosts": [ { "name": "Mixtend Demo", "email": "demo@mixtend.com" } ], "form": [ { "field_type": "company_name", "required": false, "label": "会社名", "description": "Test description", "value": "Mixtend" }, { "field_type": "guest_name", "required": true, "label": "名前", "description": "", "value": "Tomohiro Kitano" }, { "field_type": "guest_email", "required": true, "label": "メールアドレス", "description": "", "value": "guest@mixtend.com" }, { "field_type": "guest_comment", "required": false, "label": "コメント", "description": "", "value": "test" }, { "field_type": "radio", "required": true, "label": "性別", "description": "", "options": [ "男性", "女性" ], "value": "男性" }, { "field_type": "checkboxes", "required": true, "label": "趣味", "description": "", "options": [ "漫画", "カラオケ" ], "value": [ "漫画", "カラオケ" ] }, { "field_type": "dropdown", "required": true, "label": "県名", "description": "", "options": [ "東京", "埼玉" ], "value": "東京" }, { "field_type": "paragraph", "required": true, "label": "履歴", "description": "", "value": "" } ] } }
フォーマット
名前 |
データ型 |
必須 |
備考 |
---|---|---|---|
webhook_type |
string |
true |
event_confirmed |
calendar_url_path |
string |
true |
カレンダーのURLパス。チームごとに一意です。 |
team_url_path |
string |
true |
チームのURLパス。チームを一意に識別するのに使用できます。 |
calendar_url |
string |
true |
予約が行われたTimeRexカレンダーのURL。 |
event |
Object |
true |
Event object (event_confirmed) |
Webhookイベントオブジェクト (event_confirmed)
名前 |
データ型 |
必須 |
備考 |
---|---|---|---|
id |
string |
true |
イベントの一意のID |
status |
int |
true |
イベントのステータス 1 - 有効 |
duration |
int |
true |
所要時間(分) |
pre_travel_time |
int |
true |
行きの移動時間(分) |
post_travel_time |
int |
true |
帰りの移動時間(分) |
start_datetime |
string |
true |
イベントの開始日時(ISO8601に準拠) |
end_datetime |
string |
true |
イベントの終了日時(ISO8601に準拠) |
local_start_datetime |
string |
true |
TimeRexカレンダーのタイムゾーンでの日時(ISO8601に準拠) |
local_end_datetime |
string |
true |
TimeRexカレンダーのタイムゾーンでの日時(ISO8601に準拠) |
calendar_timezone |
string |
true |
IANAタイムゾーン |
guest_locale |
string |
true |
ゲストが予約した言語を示す文字列。以下の文字列が利用可能です。 ja: 日本語 |
created_at |
string |
true |
予約が行われた日時(ISO8601に準拠) |
host_cancel_url |
string |
true |
ホストが予約をキャンセルするために使うURL |
guest_cancel_url |
string |
true |
ゲストが予約をキャンセルするために使うURL |
online_meeting_provider |
string |
false |
オンライン会議のプロバイダー。利用可能なプロバイダーは以下です。
|
zoom_meeting |
Object |
false |
Zoom Meeting Object |
microsoft_teams_meeting |
Object |
false |
Microsoft Teams Meeting Object |
hosts |
Array |
true |
このイベントのホストを表すHost Objectの配列 |
form |
Array |
true |
Form Field Objectの配列。 ゲストが予約時に入力したデータが格納されます。 |
event_cancelled
TimeRexで予約がキャンセルされたときに生成されるWebhookリクエストです。次のリクエストボディが含まれています。
例
{ "webhook_type": "event_cancelled", "calendar_url_path": "215aa110", "team_url_path": "mixtend_e6ed", "calendar_url": "https://timerex.net/s/mixtend_e6ed/215aa110", "event": { "id": "1981d18a994f60e7bcc2", "status": 3, "duration": 60, "pre_travel_time": 0, "post_travel_time": 0, "start_datetime": "2020-08-26T09:00:00+00:00", "end_datetime": "2020-08-26T10:00:00+00:00", "local_start_datetime": "2020-08-26T18:00:00+09:00", "local_end_datetime": "2020-08-26T19:00:00+09:00", "calendar_timezone": "Asia/Tokyo", "guest_locale": "ja", "canceled_at": "2020-08-20T02:24:27+00:00", "cancellation_reason": "i want to cancel", "hosts": [ { "name": "Mixtend Demo", "email": "demo@mixtend.com" } ], "form": [ { "field_type": "company_name", "required": false, "label": "会社名", "description": "Test description", "value": "Mixtend" }, { "field_type": "guest_name", "required": true, "label": "名前", "description": "", "value": "Tomohiro Kitano" }, { "field_type": "guest_email", "required": true, "label": "メールアドレス", "description": "", "value": "guest@mixtend.com" }, { "field_type": "guest_comment", "required": false, "label": "コメント", "description": "", "value": "test" }, { "field_type": "radio", "required": true, "label": "性別", "description": "", "options": [ "男性", "女性" ], "value": "男性" }, { "field_type": "checkboxes", "required": true, "label": "趣味", "description": "", "options": [ "漫画", "カラオケ" ], "value": [ "漫画", "カラオケ" ] }, { "field_type": "dropdown", "required": true, "label": "県名", "description": "", "options": [ "東京", "埼玉" ], "value": "東京" }, { "field_type": "paragraph", "required": true, "label": "履歴", "description": "", "value": "history" } ] } }
フォーマット
名前 |
データ型 |
必須 |
備考 |
---|---|---|---|
webhook_type |
string |
true |
event_cancelled |
calendar_url_path |
string |
true |
カレンダーのURLパス。チームごとに一意です。 |
team_url_path |
string |
true |
チームのURLパス。チームを一意に識別するのに使用できます。 |
calendar_url |
string |
true |
予約が行われたTimeRexカレンダーのURL。 |
event |
Object |
true |
Event object (event_cancelled) |
Webhookイベントオブジェクト (event_cancelled)
名前 |
データ型 |
必須 |
備考 |
---|---|---|---|
id |
string |
true |
イベントの一意のID |
status |
integer |
true |
イベントのステータス 1 - 有効 |
duration |
integer |
true |
所要時間(分) |
pre_travel_time |
integer |
true |
行きの移動時間(分) |
post_travel_time |
integer |
true |
帰りの移動時間(分) |
start_datetime |
string |
true |
イベントの開始日時(ISO8601に準拠) |
end_datetime |
string |
true |
イベントの終了日時(ISO8601に準拠) |
local_start_datetime |
string |
true |
TimeRexカレンダーのタイムゾーンでの日時(ISO8601に準拠) |
local_end_datetime |
string |
true |
TimeRexカレンダーのタイムゾーンでの日時(ISO8601に準拠) |
calendar_timezone |
string |
true |
IANAタイムゾーン |
guest_locale |
string |
true |
ゲストが予約した言語を示す文字列。以下の文字列が利用可能です。 ja: 日本語 |
canceled_at |
string |
true |
予約がキャンセルされた日時(ISO8601に準拠) |
cancellation_reason |
string |
true |
ゲストまたはホストが予約をキャンセルした理由 |
hosts |
Array |
true |
このイベントのホストを表すHost Objectの配列 |
form |
Array |
true |
Form Field Objectの配列。 ゲストが予約時に入力したデータが格納されます。 |
Common objects
Zoom Meeting Object
名前 |
データ型 |
必須 |
備考 |
---|---|---|---|
meeting_id |
integer |
true |
ZoomミーティングのミーティングID |
join_url |
string |
true |
Zoomミーティングへの参加に使用するURL |
password |
string |
false |
Zoomミーティングに設定されたパスワード(設定された場合) |
host |
Object |
true |
Zoomミーティングのホストを表すHost Object |
Microsoft Teams Meeting Object
名前 |
データ型 |
必須 |
備考 |
---|---|---|---|
meeting_id |
string |
true |
Microsoft TeamsミーティングのミーティングID |
join_url |
string |
true |
Microsoft Teamsミーティングへの参加に使用するURL |
short_url |
string |
true |
Microsoft Teamsミーティングへの参加に使用するShort URL |
host |
Object |
true |
Microsoft Teamsミーティングのホストを表すHost Object |
Host Object
名前 |
データ型 |
必須 |
備考 |
---|---|---|---|
name |
string |
true |
ホストの公開名 |
|
string |
true |
ホストのメールアドレス |
Form Field Object
名前 |
データ型 |
必須 |
備考 |
---|---|---|---|
field_type |
string |
true |
入力項目のタイプ。以下のタイプが利用可能です。
|
required |
string |
true |
入力項目が必須かどうかを表す |
label |
string |
true |
入力項目のラベル |
description |
string |
true |
入力項目の説明 |
options |
Array |
false |
入力項目の選択肢の文字列を格納する配列。次のタイプの入力項目でのみ使用されます。
Example: [ "Option 1", "Option 2" ] |
value |
string|Array |
true |
入力項目にゲストが入力した値。 チェックボックスの場合、ゲストが選んだ選択肢の文字列を格納する配列になります。 例 "Answer" 例 (チェックボックス) [ "Answer 1", "Answer 2" ]
|
レスポンス
お使いのシステムが、TimeRex Webhookからリクエストを受信したとき、ステータスコード200のレスポンスを返却してください。
以下の場合、Webhookの送受信に失敗したと見なされます。
-
お使いのシステムが、ステータスコード4xxまたは5xxのHTTPレスポンスを返却する
-
システムへの接続がタイムアウトする(タイムアウトのデフォルト値は15秒)
-
システムへの安全なSSL接続を確立できない
送信が失敗した場合、10秒の間隔を空けて2回再試行されます。つまり、合計3回試行されます。
ログ
Webhookによるリクエストとレスポンスは全てログに記録され、Webhook設定ページから閲覧できます。表示されるログは最新の25個のみです。
参考情報
ISO8601 datetime format
https://www.iso.org/iso-8601-date-and-time-format.html
IANA timezones
https://www.iana.org/time-zones