Webhookサービス連携

2025年9月25日のプラン改定後、本機能はFreeプランではご利用いただけなくなります。プラン改定についてはこちらをご覧ください。

はじめに

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

使用例

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

設定

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

2. WebhookURLの準備

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

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

Webhook URLの準備

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

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

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

有効なWebhookURLの例

https://example.com/callback-confirmed

リクエスト

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

レスポンス

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

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

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

失敗した場合

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

エラーの通知内容

通知方法メール通知

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

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

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

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	確定に利用された空き時間リンク。空き時間リンクを一意に特定するのに利用できます。
`privateTitle`	string	true	確定に利用された空き時間リンクの管理用タイトル。
`confirmedAt`	string	true	日程調整を確定した日時。（確定した予定の日時ではありません。）
`title`	string	true	予定のタイトル。
`startDateTime`	string	true	予定の開始日時。
`endDateTime`	string	true	予定の終了日時。
`timeZone`	string	true	予定の確定者のタイムゾーン。
`organizer`	Object	true	予定の主催者。（空き時間リンクに設定されている主催者）
`attendeesFromOrganizerSide`	Array	true	予定の主催者側の同席者。
`invitee`	Object	true	予定の確定者。（空き時間リンクを受け取って日程を選んだ人）
`attendeesFromInviteeSide`	Array	true	予定の確定者側の同席者。
`onlineMeeting`	Object	true	予定のWeb会議。
`formAnswers`	Array	true	空き時間リンクに設定されているフォームの回答。
`rooms`	Array	true	予定の会議室。
`utmParameters`	Object	false	UTMパラメータ UTMパラメータが付与された空き時間リンクで確定された場合、Payloadに値が含まれます。
`source`	Object	false	日程確定した際の環境に関する情報を格納

Payload.source Object

Property名	データ型	必須	説明
`url`	Object	false	URLに関する情報を格納

Payload.source.url Object

Property名	データ型	必須	説明
`query`	String	true	確定に利用された空き時間リンクのクエリパラメータ。最大で2000文字まで。

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"
			}
		],
		"rooms": [
	 	 	{
				"name": "会議室1",
				"email": "meeting-room-1@example.com"
	 	 	}
		], 
		"utmParameters": {
	 	 	"utmSource": "test",
			"utmCampaign": "campaign test",
			"utmMedium": "medium test",
			"utmTerm": "term test",
			"utmContent": "test content"
		},
		"source": {
			"url": {
				"query": "?utm_source=test&utm_campaign&utm_medium=medium%20test&utm_term=term%20test&utm_content=test%20content"
			}
		}
	}
}

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

Response Body

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

Payload Object

Property名	データ型	必須	説明
`originalUrl`	string	true	確定に利用された空き時間リンク。空き時間リンクを一意に特定するのに利用できます。
`privateTitle`	string	true	確定に利用された空き時間リンクの管理用タイトル。
`confirmedAt`	string	true	日程調整を確定した日時。（確定した予定の日時ではありません。）
`title`	string	true	予定のタイトル。
`startDateTime`	string	true	予定の開始日時。
`endDateTime`	string	ture	予定の終了日時。
`timeZone`	string	true	予定のタイムゾーン。
`organizer`	Object	true	予定の主催者。（空き時間リンクに設定されている主催者）
`attendeesFromOrganizerSide`	Array	true	予定の主催者側の同席者。
`invitee`	Object	true	予定の確定者。（空き時間リンクを受け取って日程を選んだ人）
`attendeesFromInviteeSide`	Array	true	予定の確定者側の同席者。
`formAnswers`	Array	true	空き時間リンクに設定されているフォームの回答。
`cacelReason`	string	true	予定をキャンセルした理由。
`rooms`	Array	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が入ってしまったため。",
		"rooms": [
	 	 	{
				"name": "会議室1",
				"email": "meeting-room-1@example.com"
	 	 	}
		], 
		"canceledAt": "2023-07-01T18:00:00Z"
	}
}

条件分岐フォーム回答 (form.answered)

条件分岐フォームに回答が送信され、条件分岐の結果が確定したタイミングで送信されるイベントです。

Response Body

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

Payload Object

Property名	データ型	必須	説明
`originalUrl`	string	true	回答対象の条件分岐フォームURL。フォームを一意に特定するのに利用できます。
`privateTitle`	string	ture	条件分岐フォームの管理用タイトル。
`answeredAt`	string	true	フォームの回答日時（ISO 8601）。
`action`	Object	true	回答内容に基づく条件分岐の結果（次のアクション）
`respondent`	Object	true	フォームの回答者。
`formAnswers`	Array	true	フォームの回答内容。

Payload.action Object

回答結果に応じて遷移先（次のアクション）が決まります。`type` の値によって含まれるプロパティが変わります。

Property名	データ型	必須	説明
`type`	string	true	条件分岐先の種別。`team_availability_sharing`（空き時間リンクへ遷移）または `message`（メッセージ表示）のいずれか。
`url`	string	false	`type` が `team_availability_sharing` の場合に設定される、遷移先の空き時間リンク。
`privateTitle`	string	false	`type` が `team_availability_sharing` の場合に設定される、遷移先の空き時間リンクの管理用タイトル。
`message`	string	false	回答者に表示されるメッセージ。`type` が `message` の場合は必須、`team_availability_sharing` の場合は任意。

Payload.respondent Object

Property名	データ型	必須	説明
`name`	string	true	回答者の氏名。
`email`	string	ture	回答者のメールアドレス。
`language`	string	true	回答者の言語設定（例: `ja`）。

Payload.formAnswers Object（配列要素）

Property名	データ型	必須	説明
`questionId`	string	true	質問項目を一意に特定するID。
`question`	string	ture	質問のラベル。`name` / `email` は固定項目、それ以外はフォーム作成者が設定した質問文。
`answer`	string	true	質問に対する回答内容。

Json Sample

{
  "webhookEventName": "form.answered",
  "webhookEventId": "tp7mPJVl0oOULa9hOIM80",
  "payload": {
    "originalUrl": "https://app.spirinc.com/t/xxx/r/xxx/answer",
    "privateTitle": "セールス商談用 条件分岐フォーム",
    "answeredAt": "2023-07-01T12:00:00Z",
    "action": {
      "type": "team_availability_sharing",
      "teamAvailabilitySharingId": "xxx"
    },
    "respondent": {
      "name": "中島 昌平",
      "email": "syohei.nakazima@example.com",
      "language": "JA"
    },
    "formAnswers": [
      {
        "questionId": "xxx1",
        "question": "name",
        "answer": "中島 昌平"
      },
      {
        "questionId": "xxx2",
        "question": "email",
        "answer": "syohei.nakazima@example.com"
      },
      {
        "questionId": "xxx3",
        "question": "会社名",
        "answer": "株式会社Acme"
      },
      {
        "questionId": "xxx4",
        "question": "業種",
        "answer": "マーケティング"
      },
      {
        "questionId": "xxx5",
        "question": "企業規模",
        "answer": "100~200人"
      },
      {
        "questionId": "xxx6",
        "question": "お問い合わせ内容",
        "answer": "導入のご相談"
      }
    ]
  }
}

Webhookサービス連携のよくある質問

WebhookのIPアドレス教えてください
Webhook送信側 (Spir側) のIPアドレス固定化は実施しておりません。
そのため、個別のIPアドレスの回答は出来かねます。
ログの提供はしていますか？
本画面右下の吹き出しマークより、チャットサポートにてお問い合わせください。