💁

Webhookサービス連携

 

はじめに

💡
Webhookサービス連携はSpirで特定のイベント発生時に、指定したURLにPOSTリクエストします
 
使用例
  • Zapier、IFTTT等のアプリケーションと連携する
    • APIを通じて各サービスを連携させることが可能です
    • 例:日程確定時にSalesforceと連携する
      • Spirでは日程が確定した際、デフォルトの通知は主催者・参加者へのメール通知のみですが、webhookを活用することで外部のサービスと連携することが可能です
 

設定

💡
1. 対象のイベントイベントタイプから決める 2. webhookURLの準備 3. WebhookURLと対象のイベントをこちらのフォームからお知らせください
 

イベントタイプ

 
空き時間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秒でタイムアウト)
 
失敗した場合
  1. 10秒ごとに4回リトライします
  1. 最後のリクエストが失敗した場合エラーの通知をします
 

エラーの通知内容

  • 通知方法 メール通知
  • 通知先 チームの管理者全員
  • メールタイトル
    • 【Spir】Webhookの送信に失敗しました。
  • メール通知内容
    • 空き時間URLの管理用タイトル
      WebhookURL
      送信時刻
      HTTPレスポンスなどの送信ログ
      (送信ログにつきましては添付ファイルに記載されます。)

リクエストボディ

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

日程確定 (event.confirmed)

Response Body

Property名データ型必須説明
stringtrueWebhookのイベントタイプ。
stringtureWebhookのイベントごとに一意のid。
Objecttrue

Payload Object

Property名データ型必須説明
stringtrue確定に利用された空き時間URL。空き時間URLを一意に特定するのに利用できます。
stringtrue確定に利用された空き時間URLの管理用タイトル。
stringtrue日程調整を確定した日時。(確定した予定の日時ではありません。)
stringtrue予定のタイトル。
stringtrue予定の開始日時。
stringtrue予定の終了日時。
stringtrue予定の確定者のタイムゾーン。
Objecttrue予定の主催者。(空き時間URLに設定されている主催者)
Arraytrue予定の主催者側の同席者。
Objecttrue予定の確定者。(空き時間URLを受け取って日程を選んだ人)
Arraytrue予定の確定者側の同席者。
Objecttrue予定のWeb会議。
Arraytrue空き時間URLに設定されているフォームの回答。
ObjectfalseUTMパラメータ UTMパラメータが付与された空き時間URLで確定された場合、Payloadに値が含まれます。

Json Sample

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

Response Body

Property名データ型必須説明
stringtrueWebhookのイベントタイプ。
stringtureWebhookのイベントごとに一意のid。
Objecttrue

Payload Object

Property名データ型必須説明
stringtrue確定に利用された空き時間URL。空き時間URLを一意に特定するのに利用できます。
stringtrue確定に利用された空き時間URLの管理用タイトル。
stringtrue日程調整を確定した日時。(確定した予定の日時ではありません。)
stringtrue予定のタイトル。
stringtrue予定の開始日時。
stringture予定の終了日時。
stringtrue予定のタイムゾーン。
Objecttrue予定の主催者。(空き時間URLに設定されている主催者)
Arraytrue予定の主催者側の同席者。
Objecttrue予定の確定者。(空き時間URLを受け取って日程を選んだ人)
Arraytrue予定の確定者側の同席者。
Arraytrue空き時間URLに設定されているフォームの回答。
stringtrue予定をキャンセルした理由。
stringtrue予定をキャンセルした日時。
 

Json Sample

 

ログの提供

お問い合わせください