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
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 |
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: |
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_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 |
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 |
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 |
|
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:
|
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.
Example: [ "Option 1", "Option 2" ] |
value |
string|Array |
true |
The value entered by the guest for this form field. 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