ホームに戻る

ヘルプページ

外部サービス連携

Webhookサービス連携

はじめに

💡Webhookサービス連携はSpirで特定のイベント発生時に、指定したURLにPOSTリクエストします

使用例

Zapier、IFTTT等のアプリケーションと連携する
APIを通じて各サービスを連携させることが可能です
- 例：日程確定時にSalesforceと連携する
  Spirでは日程が確定した際、デフォルトの通知は主催者・参加者へのメール通知のみですが、webhookを活用することで外部のサービスと連携することが可能です

設定

1. 対象のイベントをイベントタイプから決める

2. WebhookURLの準備

3. WebhookURLと対象のイベントをこちらのフォームからお知らせください

イベントタイプ

日程確定 (event.confirmed)

日程確定のキャンセル（event.canceled）

空き時間URLのみが対象
すべての空き時間URLがwebhookの送信対象になります（個別に設定することはできません）

Webhook URLの準備

Webhookサービス連携には、Spirからのリクエストを受信できるhttpsエンドポイント（以下、WebhookURL）を準備する必要があります

WebhookURLは、以下の点にご注意ください

HTTPS通信
localhostのURLは不可
IPアドレスは使用不可

有効なWebhookURLの例

https://example.com/callback-confirmed

Webhook URL設定数の上限に関して

1イベントに対して1つのWebhook URLを登録

1イベントに対して2つ以上のURLを登録したい場合はお問い合わせください

リクエスト

SpirはPOSTメソッドでリクエストしますリクエストボディはJSONオブジェクトに基づいており、イベントタイプによって異なります

レスポンス

💡設定したWebhookURLが、Spirからリクエストを受信したとき、ステータスコード200のレスポンスを返却してください

以下の場合、Webhookの送受信に失敗したと見なされます

WebhookURLがステータスコード3xx、4xxまたは5xxのHTTPレスポンスを返却した場合
システムへの接続がタイムアウトした場合（リクエストは30秒でタイムアウト）

失敗した場合

10秒ごとに4回リトライします
最後のリクエストが失敗した場合エラーの通知をします

エラーの通知内容

通知方法メール通知

通知先チームの管理者全員

メールタイトル
【Spir】Webhookの送信に失敗しました。

メール通知内容
空き時間URLの管理用タイトル

WebhookURL

送信時刻

HTTPレスポンスなどの送信ログ

（送信ログにつきましては添付ファイルに記載されます。）

リクエストボディ

リクエストボディはJSONオブジェクトに基づいており、イベントタイプによって異なります

日程確定 (event.confirmed)

Response Body

Property名	データ型	必須	説明
`webhookEventName`	string	true	Webhookのイベントタイプ。
`webhookEventId`	string	ture	Webhookのイベントごとに一意のid。
`payload`	Object	true

Payload Object

Property名	データ型	必須	説明
`originalUrl`	string	true	確定に利用された空き時間URL。空き時間URLを一意に特定するのに利用できます。
`privateTitle`	string	true	確定に利用された空き時間URLの管理用タイトル。
`confirmedAt`	string	true	日程調整を確定した日時。（確定した予定の日時ではありません。）
`title`	string	true	予定のタイトル。
`startDateTime`	string	true	予定の開始日時。
`endDateTime`	string	true	予定の終了日時。
`timeZone`	string	true	予定の確定者のタイムゾーン。
`organizer`	Object	true	予定の主催者。（空き時間URLに設定されている主催者）
`attendeesFromOrganizerSide`	Array	true	予定の主催者側の同席者。
`invitee`	Object	true	予定の確定者。（空き時間URLを受け取って日程を選んだ人）
`attendeesFromInviteeSide`	Array	true	予定の確定者側の同席者。
`onlineMeeting`	Object	true	予定のWeb会議。
`formAnswers`	Array	true	空き時間URLに設定されているフォームの回答。
`utmParameters`	Object	false	UTMパラメータ UTMパラメータが付与された空き時間URLで確定された場合、Payloadに値が含まれます。

Json Sample

{
	"webhookEventName": "event.confirmed",
	"webhookEventId": "tp7mPJVl0oOULa9hOIM80",
	"payload": {
		"originalUrl": "https://app.spirinc.com/t/xxx/as/xxx/confirm",
		"privateTitle": "セールス商談用URL",
		"confirmedAt": "2023-07-01T12:00:00Z",
		"startDateTime": "2023-07-05T12:00:00Z",
		"endDateTime": "2023-07-05T13:00:00Z",
		"timeZone": "Asia/Tokyo",
		"title": "〇〇商談",
		"organizer": {
			"name": "伊藤 ひろき",
			"email": "hiroki.ito@example.com"
		},
		"attendeesFromOrganizerSide": [
			{
				"name": "山田 剛",
				"email": "go.yamadaa@example.com"
			}
		],
		"invitee": {
			"name": "中島 昌平",
			"email": "syohei.nakazima@example.com",
			"language": "JA"
		},
		"attendeesFromInviteeSide": [
			{
				"name": "澤田 充",
				"email": "mitsuru.sawada@example.com"
			}
		],
		"onlineMeeting": {
			"type": "zoom",
			"url": "https://zoom~",
			"password": "abcd1234"
		},
		"formAnswers": [
			{
				"questionId": "xxx1",
				"question": "name",
				"answer": "中島 昌平"
			},
			{
				"questionId": "xxx2",
				"question": "email",
				"answer": "syohei.nakazima@example.com"
			},
			{
				"questionId": "xxx3",
				"question": "会社名",
				"answer": "株式会社Acme"
			},
			{
				"questionId": "xxx4",
				"question": "電話番号",
				"answer": "08012345678"
			}
		],
		"utmParameters": {
		  "utmSource": "test",
			"utmCampaign": "campaign test",
			"utmMedium": "medium test",
			"utmTerm": "term test",
			"utmContent": "test content"
		}
	}
}

日程確定のキャンセル(event.canceled)

Response Body

Property名	データ型	必須	説明
`webhookEventName`	string	true	Webhookのイベントタイプ。
`webhookEventId`	string	ture	Webhookのイベントごとに一意のid。
`payload`	Object	true

Payload Object

Property名	データ型	必須	説明
`originalUrl`	string	true	確定に利用された空き時間URL。空き時間URLを一意に特定するのに利用できます。
`privateTitle`	string	true	確定に利用された空き時間URLの管理用タイトル。
`confirmedAt`	string	true	日程調整を確定した日時。（確定した予定の日時ではありません。）
`title`	string	true	予定のタイトル。
`startDateTime`	string	true	予定の開始日時。
`endDateTime`	string	ture	予定の終了日時。
`timeZone`	string	true	予定のタイムゾーン。
`organizer`	Object	true	予定の主催者。（空き時間URLに設定されている主催者）
`attendeesFromOrganizerSide`	Array	true	予定の主催者側の同席者。
`invitee`	Object	true	予定の確定者。（空き時間URLを受け取って日程を選んだ人）
`attendeesFromInviteeSide`	Array	true	予定の確定者側の同席者。
`formAnswers`	Array	true	空き時間URLに設定されているフォームの回答。
`cacelReason`	string	true	予定をキャンセルした理由。
`canceledAt`	string	true	予定をキャンセルした日時。

Json Sample

{
	"webhookEventName": "event.canceled",
  "webhookEventId": "tp7mPJVl0oOULa9hOIM80",
	"payload": {
	  "originalUrl": "https://app.spirinc.com/t/xxx/as/xxx/confirm",
		"privateTitle": "セールス商談用URL",
		"confirmedAt": "2023-07-01T12:00:00Z"
		"startDateTime": "2023-07-05T12:00:00Z",
		"endDateTime": "2023-07-05T13:00:00Z",
		"timeZone": "Asia/Tokyo",
		"title": "〇〇商談",
		"organizer": {
			"name": "伊藤 ひろき",
			"email": "hiroki.ito@example.com"
		},
		"attendeesFromOrganizerSide": [
			{
				"name": "山田 剛",
				"email": "go.yamadaa@example.com"
			}
		],
		"invitee": {
			"name": "中島 昌平"
			"email": "syohei.nakazima@example.com",
			"language": "JA"
		},
		"attendeesFromInviteeSide": [
			{
				"name": "澤田 充",
				"email": "mitsuru.sawada@example.com"
			}
		],
　　　　　　　"formAnswers": [
			{
				"questionId": "xxx1",
				"question": "name",
				"answer": "中島 昌平"
			},
			{
				"questionId": "xxx2",
				"question": "email",
				"answer": "syohei.nakazima@example.com"
			},
			{
				"questionId": "xxx3",
				"question": "会社名",
				"answer": "株式会社Acme"
			},
			{
				"questionId": "xxx4",
				"question": "電話番号",
				"answer": "08012345678"
			}
		],
   "cancelReason": "急な社外mtgが入ってしまったため。",
   "canceledAt": "2023-07-01T18:00:00Z"
	}
}

ログの提供

お問い合わせください