Connecting external services
      Back to home
      1. User's guide
      2. Connecting external services

      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

      • 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

      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. 

      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
      2. 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
      webhookEventName string true Event type of the webhook.
      webhookEventId string ture Unique id for each webhook event.
      payload Object true  

      Payload Object

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

      Json Sample

      {
      	"webhookEventName": "event.confirmed",
      	"webhookEventId": "tp7mPJVl0oOULa9hOIM80",
      	"payload": {
      		"originalUrl": "https://app.spirinc.com/t/xxx/as/xxx/confirm",
      		"privateTitle": "URL for Sales Discussion",
      		"confirmedAt": "2023-07-01T12:00:00Z",
      		"startDateTime": "2023-07-05T12:00:00Z",
      		"endDateTime": "2023-07-05T13:00:00Z",
      		"timeZone": "Asia/Tokyo",
      		"title": "Sales Discussion",
      		"organizer": {
      			"name": "Hiroki Ito",
      			"email": "hiroki.ito@example.com"
      		},
      		"attendeesFromOrganizerSide": [
      			{
      				"name": "Go Yamada",
      				"email": "go.yamadaa@example.com"
      			}
      		],
      		"invitee": {
      			"name": "Shohei Nakazima",
      			"email": "syohei.nakazima@example.com",
      			"language": "JA"
      		},
      		"attendeesFromInviteeSide": [
      			{
      				"name": "Mitsuru Sawada",
      				"email": "mitsuru.sawada@example.com"
      			}
      		],
      		"onlineMeeting": {
      			"type": "zoom",
      			"url": "https://zoom~",
      			"password": "abcd1234"
      		},
      		"formAnswers": [
      			{
      				"questionId": "xxx1",
      				"question": "name",
      				"answer": "Shohei Nakazima"
      			},
      			{
      				"questionId": "xxx2",
      				"question": "email",
      				"answer": "syohei.nakazima@example.com"
      			},
      			{
      				"questionId": "xxx3",
      				"question": "Company Name",
      				"answer": "Acme Inc."
      			},
      			{
      				"questionId": "xxx4",
      				"question": "Phone Number",
      				"answer": "08012345678"
      			}
      		],
      		"utmParameters": {
      		  "utmSource": "test",
      			"utmCampaign": "campaign test",
      			"utmMedium": "medium test",
      			"utmTerm": "term test",
      			"utmContent": "test content"
      		}
      	}
      }

      Event Cancellation (event.canceled)

      Response Body

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

      Payload Object

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

      JSON Sample

      jsonCopy code
      {
      	"webhookEventName": "event.canceled",
        "webhookEventId": "tp7mPJVl0oOULa9hOIM80",
      	"payload": {
      	  "originalUrl": "https://app.spirinc.com/t/xxx/as/xxx/confirm",
      		"privateTitle": "Sales Discussion URL",
      		"confirmedAt": "2023-07-01T12:00:00Z"
      		"startDateTime": "2023-07-05T12:00:00Z",
      		"endDateTime": "2023-07-05T13:00:00Z",
      		"timeZone": "Asia/Tokyo",
      		"title": "Sales Discussion",
      		"organizer": {
      			"name": "Hiroki Ito",
      			"email": "hiroki.ito@example.com"
      		},
      		"attendeesFromOrganizerSide": [
      			{
      				"name": "Go Yamada",
      				"email": "go.yamadaa@example.com"
      			}
      		],
      		"invitee": {
      			"name": "Shohei Nakajima"
      			"email": "syohei.nakazima@example.com",
      			"language": "JA"
      		},
      		"attendeesFromInviteeSide": [
      			{
      				"name": "Mitsuru Sawada",
      				"email": "mitsuru.sawada@example.com"
      			}
      		],
         "formAnswers": [
      			{
      				"questionId": "xxx1",
      				"question": "name",
      				"answer": "Shohei Nakajima"
      			},
      			{
      				"questionId": "xxx2",
      				"question": "email",
      				"answer": "syohei.nakazima@example.com"
      			},
      			{
      				"questionId": "xxx3",
      				"question": "Company Name",
      				"answer": "Acme Inc."
      			},
      			{
      				"questionId": "xxx4",
      				"question": "Phone Number",
      				"answer": "08012345678"
      			}
      		],
         "cancelReason": "Had an urgent external meeting.",
         "canceledAt": "2023-07-01T18:00:00Z"
      	}
      }
       

      Providing Logs

      Contact us for logs.