Webhook API – TimeRex Support

Introduction

Webhook API Integration lets your service or system receive requests in near real time when certain events occur on TimeRex.

Some common use-cases for integrating with TimeRex Webhook:

Insert booking details into your CRM
Add booking details into a SaaS tool
Integrate with a call center solution
And more

Availability

Webhook API is available for all users on a Premium TimeRex plan.

Setup

Webhooks can be setup from the following pages on your account.

Personal Settings → Integrations
Team Settings → Integrations

Before setting up a webhook you will need to prepare an https endpoint (here after referred to as webhook url), that is capable of accepting requests from TimeRex.

Please note the following requirements for the webhook url.

Only HTTPS urls are supported
The webhook url must have a valid SSL certificate associated with it
Self signed certificates are not accepted
localhost urls are not supported
Only port 443 is supported for SSL communication
IP addresses are not supported

Some examples of valid webhook urls

https://yourserver.com/callback
https://api.yourserver.com/callback
https://api.yourserver.com:443

Some examples of invalid webhook urls

http://yourserver.com/callback
http://localhost/
https://api.yourserver.com:8000

Once you have a webhook url, you can link it to TimeRex from the integrations page.

Note: You can generate a webhook url for testing using a service like

https://requestbin.com/

On setting up the webhook a security token is also generated. It is highly recommended that you use this security token to validate that a request originated from TimeRex.

Request

TimeRex Webhook API makes requests using a POST request type.

Headers

Every webhook request from TimeRex will contain the following Header keys.

{
    "content-type": "application/json",
    "accept": "application/json",
    "user-agent": "TimeRex API v",
    "authorization": ""
}

Event Types

There are currently two types of events send by the TimeRex webhook. These are:

event_confirmedIt is recommended to check the authorization header to validate that the security token matches the token in your TimeRex account. If it doesn’t match you should discard the request.

event_cancelled

Further details are explained below.

Payload

The payload is based a JSON object and it differs based on the event type. The payload and data format is explained below.

event_confirmed

This is the webhook request that is generated when a booking is confirmed on TimeRex. It contains the following payload.

Example

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

Data format

Name	Datatype	Required	Remarks
webhook_type	string	true	event_confirmed
calendar_url_path	string	true	URL path of the calendar. This is unique for a team.
team_url_path	string	true	URL path of the team. This can be used to uniquely identify a team.
calendar_url	string	true	The TimeRex calendar URL where this booking was made.
event	Object	true	Event object (event_confirmed)

Event Object (event_confirmed)

Name	Datatype	Required	Remarks
id	string	true	Unique id for the event
status	int	true	Status for the event. 1 - Active 2 - Cancelled by host 3 - Cancelled by guest
duration	int	true	The event duration in minutes
pre_travel_time	int	true	Pre travel time for the event in minutes
post_travel_time	int	true	Post travel time for the event in minutes
start_datetime	string	true	An ISO8601 datetime string
end_datetime	string	true	An ISO8601 datetime string
local_start_datetime	string	true	An ISO8601 datetime string in the calendar timezone
local_end_datetime	string	true	An ISO8601 datetime string in the calendar timezone
calendar_timezone	string	true	IANA timezone
guest_locale	string	true	The locale shortcode of the guest who made the booking. Available locales are: ja: Japanese en: English
created_at	string	true	An ISO8601 datetime string indicating when the booking was created
host_cancel_url	string	true	The url that can be used by the host to cancel this booking
guest_cancel_url	string	true	The url that can be used by the guest to cancel this booking
online_meeting_provider	string	false	The online meeting provider for this booking. Available providers are: zoom microsoft_teams google_meet
zoom_meeting	Object	false	Zoom Meeting Object
microsoft_teams_meeting	Object	false	Microsoft Teams Meeting Object
google_meet_meeting	Object	false	Google Meet Meeting Object
hosts	Array	true	An array of Host Objects indicating the hosts of this event
form	Array	true	An array of Form Field Objects. This contains the data entered by the guest when making this booking
url_params	Array	true	An array of Url Param objects

event_cancelled

This is the webhook request that is generated when a booking is cancelled on TimeRex. It contains the following payload.

Example

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

Parameters

Name	Datatype	Required	Remarks
webhook_type	string	true	event_cancelled
calendar_url_path	string	true	URL path of the calendar. This is unique for a team.
team_url_path	string	true	URL path of the team. This can be used to uniquely identify a team.
calendar_url	string	true	The TimeRex calendar URL where this booking was made.
event	Object	true	Event object (event_cancelled)

Event Object (event_cancelled)

Name	Datatype	Required	Remarks
id	string	true	Unique id for the event
status	integer	true	Status for the event. 1 - Active 2 - Cancelled by host 3 - Cancelled by guest
duration	integer	true	The event duration in minutes
pre_travel_time	integer	true	Pre travel time for the event in minutes
post_travel_time	integer	true	Post travel time for the event in minutes
start_datetime	string	true	An ISO8601 datetime string
end_datetime	string	true	An ISO8601 datetime string
local_start_datetime	string	true	An ISO8601 datetime string in the calendar timezone
local_end_datetime	string	true	An ISO8601 datetime string in the calendar timezone
calendar_timezone	string	true	IANA timezone
guest_locale	string	true	The locale shortcode of the guest who made the booking. Available locales are: ja: Japanese en: English
canceled_at	string	true	An ISO8601 datetime string indicating when the booking was cancelled
cancellation_reason	string	true	The reason for cancelling this meeting as provided by the guest or host
hosts	Array	true	An array of Host Objects indicating the hosts of this event
form	Array	true	An array of Form Field Objects. This contains the data entered by the guest when making this booking

Common objects

Zoom Meeting Object

Name	Datatype	Required	Remarks
meeting_id	integer	true	The Meeting id for the zoom meeting
join_url	string	true	The URL that can be used to join the zoom meeting
password	string	false	The password (if any) that was set for this meeting
host	Object	true	A Host Object indicating the host of this zoom meeting

Microsoft Teams Meeting Object

Name	Datatype	Required	Remarks
meeting_id	string	true	The Meeting id for the microsoft teams meeting
join_url	string	true	The URL that can be used to join the microsoft teams meeting
short_url	string	true	The short URL that can be used to join the microsoft teams meeting
host	Object	true	A Host Object indicating the host of this microsoft teams meeting

Google Meet Meeting Object

Name	Datatype	Required	Remarks
meeting_id	string	true	The Meeting id for the Google Meet meeting
join_url	string	true	The URL that can be used to join the Google Meet meeting
host	Object	true	A Host Object indicating the host of this google meet meeting

Host Object

Name	Datatype	Required	Remarks
name	string	true	The name of the host
email	string	true	The email of the host

Form Field Object

Name	Datatype	Required	Remarks
field_type	string	true	The field type of the form field. Available types are: company_name guest_name guest_email guest_comment radio checkboxes dropdown paragraph
required	string	true	Whether data input is required for this field.
label	string	true	The label for this form field.
description	string	true	The description for this form field.
options	Array	false	A string array of options for this form field. This parameter is only used for the following field types. radio checkboxes dropdown Example: [ "Option 1", "Option 2" ]
value	string\|Array	true	The value entered by the guest for this form field. For checkboxes this will be a string array of options selected by the guest. Example: "Answer" Example (for checkboxes): [ "Answer 1", "Answer 2" ]

Response

On receiving a request from a TimeRex webhook your server is expected is return a 200 response as soon as possible.

The webhook delivery is considered a failure in the following scenarios:

Your server returns a 400 or 500 series http response
The connection to your server timed out (The default timeout is 15 seconds)
A secure SSL connection could not be established to your server

In the event of a delivery failure, the delivery will be retried twice at 10 second intervals for a total of 3 tries.

Logging

All webhook delivery requests and responses are logged and are available for viewing from your webhook settings page. Please note that only the latest 25 log items are available for viewing.

Addendum

ISO8601 datetime format
https://www.iso.org/iso-8601-date-and-time-format.html

IANA timezones
https://www.iana.org/time-zones

Introduction

Availability

Setup

Request

Headers

Event Types

Payload

event_confirmed

Example

Data format

Event Object (event_confirmed)

event_cancelled

Example

Parameters

Event Object (event_cancelled)

Common objects

Zoom Meeting Object

Microsoft Teams Meeting Object

Google Meet Meeting Object

Host Object

Form Field Object

Response

Logging

Addendum

Related articles