Webhook API

  • 更新

はじめに

Webhook API サービス連携により、TimeRexで特定のイベントが発生したときに、指定したURLにPOSTすることができます。

主な使用例は、こちらです。

  • CRMに予約の詳細を追加する
  • SaaSツールに予約の詳細を追加する
  • 独自サービスと統合する

 

ご利用条件

Webhook APIは、プレミアムプランのすべてのユーザーが利用できます。

 

設定

Webhookは、以下のページから設定できます。

アカウント設定→サービス連携
チーム設定→サービス連携

55d24b22-3523-464a-b13b-688ee775808a.png

 

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にリンクできます。

8d02e5eb-d984-4e9a-98d4-d7122699a654.png

※ 次のようなサービスを利用して、テスト用の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
  • microsoft_teams

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 - 有効
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

 

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

ホストの公開名

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

 

 

 

 

 

 

 

 

 

 

 

 

関連記事