Webhook API – TimeRex サポート

はじめに

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を生成できます。

https://requestbin.com/

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 - 有効 2 - ホストによるキャンセル 3 - ゲストによるキャンセル
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: 日本語 en: 英語
created_at	string	true	予約が行われた日時（ISO8601に準拠）
host_cancel_url	string	true	ホストが予約をキャンセルするために使うURL
guest_cancel_url	string	true	ゲストが予約をキャンセルするために使うURL
online_meeting_provider	string	false	オンライン会議のプロバイダー。利用可能なプロバイダーは以下です。 zoom
zoom_meeting	Object	false	Zoom 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 - 有効 2 - ホストによるキャンセル 3 - ゲストによるキャンセル
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: 日本語 en: 英語
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

Host Object

名前	データ型	必須	備考
name	string	true	ホストの公開名
email	string	true	ホストのメールアドレス

Form Field Object

名前	データ型	必須	備考
field_type	string	true	入力項目のタイプ。以下のタイプが利用可能です。 company_name guest_name guest_email guest_comment radio checkboxes dropdown paragraph
required	string	true	入力項目が必須かどうかを表す
label	string	true	入力項目のラベル
description	string	true	入力項目の説明
options	Array	false	入力項目の選択肢の文字列を格納する配列。次のタイプの入力項目でのみ使用されます。 radio checkboxes dropdown 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

はじめに

ご利用条件

設定

Webhook URLについて

リクエスト

リクエストヘッダ

イベントタイプ

リクエストボディ

event_confirmed

例

フォーマット

Webhookイベントオブジェクト (event_confirmed)

event_cancelled

例

フォーマット

Webhookイベントオブジェクト (event_cancelled)

Common objects

Zoom Meeting Object

Host Object

Form Field Object

レスポンス

ログ

参考情報

関連記事