💁

Creating a webhook

⚠️

The help page has been moved here.

This page is not updated, so please refer to the above for the latest information.

Introduction

💡

Webhook service integration allows Spir to send POST requests to specified URLs upon specific events.

Usage Example

Integrating with applications like Zapier, IFTTT, etc.

It enables integrating various services through APIs.

Example: Integrating with Salesforce upon event confirmation

While Spir defaults to sending email notifications to the organizer and attendees upon event confirmation, leveraging webhook enables integration with external services.

Configuration

💡

1. Decide the target event from Event Types 2. Prepare the Webhook URL 3. Notify us of the Webhook URL and the target event using this form

Event Types

Event Confirmation (event.confirmed)

Event Cancellation (event.canceled)

Targeting only the template URL All template URLs are automatically configured as Webhook targets (cannot be individually configured)

Preparation of Webhook URL

For Webhook service integration, you need to prepare an HTTPS endpoint (Webhook URL) capable of receiving requests from Spir.

Take note of the following regarding the Webhook URL:

HTTPS communication

localhost URLs not supported

IP addresses not supported

Examples of valid Webhook URLs

https://example.com/callback-confirmed

Limit on the Number of Webhook URL Settings

For registering two or more URLs for one event, please contact us.

Request

Spir uses the POST method for requests. The request body is based on a JSON object and varies based on the event type. For detailed request specifics, check here

Response

💡

When the configured Webhook URL receives a request from Spir, please return a response with status code 200.

The following conditions are considered failures in Webhook transmission:

When the Webhook URL returns HTTP responses with status codes 3xx, 4xx, or 5xx

When there's a timeout connecting to the system (requests time out after 30 seconds)

In case of failure

Retry every 10 seconds up to 4 times

Notify errors after the final unsuccessful request

Error Notification Content

Notification Method: Email notification

Recipients: All team administrators

Email Title

【Spir】Webhook Transmission Failed

Email Notification Content

Title for managing availability URL

Webhook URL

Time of transmission

Transmission logs including HTTP responses

(Transmission logs will be included as attachments.)

Request Body

The request body is based on a JSON object and varies based on the event type.

Event Confirmation (event.confirmed)

Response Body

Property Name	Data Type	Required	Description
	string	true	Event type of the webhook.
	string	ture	Unique id for each webhook event.
	Object	true

Payload Object

Property Name	Data Type	Required	Description
	string	true	Availability URL used for confirmation. Can be used to uniquely identify the availability URL.
	string	true	Title used for managing the availability URL used for confirmation.
	string	true	Date and time when the schedule was confirmed (not the date and time of the confirmed schedule).
	string	true	Title of the schedule.
	string	true	Start date and time of the schedule.
	string	true	End date and time of the schedule.
	string	true	Timezone of the schedule confirmant.
	Object	true	Organizer of the schedule (organizer set in the availability URL).
	Array	true	Attendees from the organizer's side of the schedule.
	Object	true	Confirmer of the schedule (individual who received the availability URL and selected the schedule).
	Array	true	Attendees from the confirmer's side of the schedule.
	Object	true	Schedule's video call details.
	Array	true	Responses to forms set in the availability URL.
	Object	false	UTM Parameters If the schedule was confirmed with UTM parameters, the payload will contain their values.

Json Sample

Event Cancellation (event.canceled)

Response Body

Property Name	Data Type	Required	Description
	string	true	Event type of the webhook.
	string	ture	Unique id for each webhook event.
	Object	true

Payload Object

Property Name	Data Type	Required	Description
	string	true	Availability URL used for confirmation. Can be used to uniquely identify the availability URL.
	string	true	Title used for managing the availability URL used for confirmation.
	string	true	Date and time when the schedule was confirmed (not the date and time of the confirmed schedule).
	string	true	Title of the schedule.
	string	true	Start date and time of the schedule.
	string	true	End date and time of the schedule.
	string	true	Timezone of the schedule.
	Object	true	Organizer of the schedule (organizer set in the availability URL).
	Array	true	Attendees from the organizer's side of the schedule.
	Object	true	Confirmer of the schedule (individual who received the availability URL and selected the schedule).
	Array	true	Attendees from the confirmer's side of the schedule.
	Array	true	Responses to forms set in the availability URL.
	string	true	Reason for schedule cancellation.
	string	true	Date and time when the schedule was canceled.

JSON Sample

Providing Logs

Post on X