Webhook（API連携）

はじめに

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": ""
            }
        ],
        "url_params": [
            {
                "utm_source": "example"
            },
            {
                "utm_medium": "email"
            },
            {
                "utm_campaign": "footer_banner"
            }
        ]
    }
}

フォーマット

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

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"
            }
        ]
    }
}

フォーマット

Common objects

Zoom Meeting Object

Form Field Object

[
"Option 1",
"Option 2"
]

"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