💁

Creating a webhook

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

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

Limit on the Number of Webhook URL Settings

Register one Webhook URL for one event.
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
  1. Retry every 10 seconds up to 4 times
  1. 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 NameData TypeRequiredDescription
stringtrueEvent type of the webhook.
stringtureUnique id for each webhook event.
Objecttrue

Payload Object

Property NameData TypeRequiredDescription
stringtrueAvailability URL used for confirmation. Can be used to uniquely identify the availability URL.
stringtrueTitle used for managing the availability URL used for confirmation.
stringtrueDate and time when the schedule was confirmed (not the date and time of the confirmed schedule).
stringtrueTitle of the schedule.
stringtrueStart date and time of the schedule.
stringtrueEnd date and time of the schedule.
stringtrueTimezone of the schedule confirmant.
ObjecttrueOrganizer of the schedule (organizer set in the availability URL).
ArraytrueAttendees from the organizer's side of the schedule.
ObjecttrueConfirmer of the schedule (individual who received the availability URL and selected the schedule).
ArraytrueAttendees from the confirmer's side of the schedule.
ObjecttrueSchedule's video call details.
ArraytrueResponses to forms set in the availability URL.
ObjectfalseUTM Parameters If the schedule was confirmed with UTM parameters, the payload will contain their values.
 

Json Sample

Event Cancellation (event.canceled)

Response Body

Property NameData TypeRequiredDescription
stringtrueEvent type of the webhook.
stringtureUnique id for each webhook event.
Objecttrue

Payload Object

Property NameData TypeRequiredDescription
stringtrueAvailability URL used for confirmation. Can be used to uniquely identify the availability URL.
stringtrueTitle used for managing the availability URL used for confirmation.
stringtrueDate and time when the schedule was confirmed (not the date and time of the confirmed schedule).
stringtrueTitle of the schedule.
stringtrueStart date and time of the schedule.
stringtrueEnd date and time of the schedule.
stringtrueTimezone of the schedule.
ObjecttrueOrganizer of the schedule (organizer set in the availability URL).
ArraytrueAttendees from the organizer's side of the schedule.
ObjecttrueConfirmer of the schedule (individual who received the availability URL and selected the schedule).
ArraytrueAttendees from the confirmer's side of the schedule.
ArraytrueResponses to forms set in the availability URL.
stringtrueReason for schedule cancellation.
stringtrueDate and time when the schedule was canceled.
 

JSON Sample

 

Providing Logs

Contact us for logs.