Webhookの使い方 - Jicoo Developer Potal

はじめに

WebhookはJicooで特定のイベント発生時に、指定したURLにPOSTリクエストを送信することができます。
POSTデータの詳細はこちら
Webhook schema

Webhookを設定すると、署名シークレットが生成されます。この署名シークレットを使用して、リクエストがJicooから送信されたものか検証することを、強く推奨します。

Webhookを利用するために事前にProプランを契約し、ダッシュボードからwebhook endpointを作成する必要があります。
https://www.jicoo.com/dashboard/webhooks

リクエスト

Jicoo Webhook APIは、POSTメソッドで指定されたURLをリクエストします。

リクエストヘッダ

JicooからのWebhookリクエストヘッダには、必ず以下のキーが含まれます。

{
    "content-type": "application/json",
    "Jicoo-Webhook-Signature": "署名"
}

Jicoo-Webhook-Signatureヘッダを使用して、POSTリクエストがJicooから送信されたリクエストか確認することを推奨します。一致しない場合は、リクエストを破棄してください。

署名の検証

Jicoo が Webhook エンドポイントに送信するイベントを検証します。
各イベントのJicoo-Webhook-Signatureヘッダに署名を含めることにより、Jicooはエンドポイントに送信する Webhookイベントに必要に応じて署名できます。これにより、イベントがJicoo によって送信されたことを検証できます。署名を検証するには手動でお客様独自のソリューションを実装する必要があります。

署名の検証を可能にするには、あらかじめダッシュボードのWebhookの設定からエンドポイントのシークレットを取得しておく必要があります。シークレットを取得するエンドポイントを選択し、クリックして表示ボタンをクリックします。

Jicoo は、エンドポイントごとに一意の署名シークレットを生成します。さらに、複数のエンドポイントを使用する場合は、署名を検証するエンドポイントごとにシークレットを取得する必要があります。この設定後、Jicooはエンドポイントに送信する各Webhookへの署名を開始します。

署名付きイベントに含まれるJicoo-Webhook-Signatureヘッダには、タイムスタンプと署名が含まれます。タイムスタンプの前には t=が付けられ、各署名の前には「スキーム」が付けられます。スキームはvで始まり、その後に整数が続きます。現在、本番環境で有効な署名スキーマは、v1のみです。

Jicoo-Webhook-Signature: t=1662520836,v1=85c11d0c60d680ab186996f934c7dcfe64da7d925f64e9b2e4d35d1fb73d6e5f

Jicooは、SHA-256 を使用したハッシュベースのメッセージ認証コード (HMAC) を使用して署名を生成します。

ステップ 1: ヘッダからタイムスタンプと署名を抽出する

要素のリストを取得するには、, 文字を区切り文字として使用してヘッダを分割します。次に、各要素を=文字を区切り文字として使用して区切り、接頭語と値のペアを取得します。

接頭語tの値はタイムスタンプに対応し、v1は署名に対応します。他のすべての要素は破棄できます。

ステップ 2: 署名検証用の文字列を準備する

署名検証用の文字列は以下を連結することで作成されます。

タイムスタンプ (文字列として)
文字 .
実際の JSON ペイロード (リクエスト本文)

ステップ 3: 想定される署名を決定する

SHA256 ハッシュ関数を使用して HMAC を計算します。エンドポイントの署名シークレットをキーとして使用し、署名検証用の文字列をメッセージとして使用します。

ステップ 4: 署名を比較する

ヘッダ内の署名を想定される署名と比較します。
一致する場合、現在のタイムスタンプと受信したタイムスタンプの差を計算し、その差が許容範囲内かどうかを判断します。タイミング攻撃から保護するには、サービスとしての許容範囲を決め、その許容範囲より古いWebhookを受信した場合拒否するようにソリューションを作成する必要があります。

イベントタイプ

現在、Jicoo Webhookにより送信されるイベントタイプは、以下に定義されています。

event property

guest_booked

ゲストによって予約が作成されたときに生成されるWebhookリクエストです。

{
  "createdAt": "2020-11-23T17:51:19.000Z",
  "event": "guest_booked",
  "object": {
    "status": "open",
    "timeZone": "America/New_York",
    "startedAt": "2022-09-01T17:00:00.000Z",
    "endedAt": "2022-09-01T18:00:00.000Z",
    "createdAt": "2020-11-23T17:51:18.341Z",
    "updatedAt": "2020-11-23T17:51:18.341Z",
    "uid": "ACDADADASS",
    "eventTypeUid": "YYYYYYY",
    "contact": {
      "email": "example@example.com",
      "name": "John Doe"
    },
    "answers": [{
      "question": "知ったきっかけは？",
      "content": ["SNS", "DM"]
    }]
  }
}

guest_rescheduled

ゲストによって予約の日程が変更されたときに生成されるWebhookリクエストです。

{
  "createdAt": "2020-11-23T17:51:19.000Z",
  "event": "guest_rescheduled",
  "object": {
    "status": "open",
    "timeZone": "America/New_York",
    "startedAt": "2022-09-01T17:00:00.000Z",
    "endedAt": "2022-09-01T18:00:00.000Z",
    "createdAt": "2020-11-23T17:51:18.341Z",
    "updatedAt": "2020-11-23T17:51:18.341Z",
    "uid": "ACDADADASS",
    "eventTypeUid": "YYYYYYY",
    "contact": {
      "email": "example@example.com",
      "name": "John Doe"
    },
    "answers": [{
      "question": "知ったきっかけは？",
      "content": ["SNS", "DM"]
    }]
  }
}

host_rescheduled

ホストによって予約の日程が変更されたときに生成されるWebhookリクエストです。

{
  "createdAt": "2020-11-23T17:51:19.000Z",
  "event": "host_rescheduled",
  "object": {
    "status": "open",
    "timeZone": "America/New_York",
    "startedAt": "2022-09-01T17:00:00.000Z",
    "endedAt": "2022-09-01T18:00:00.000Z",
    "createdAt": "2020-11-23T17:51:18.341Z",
    "updatedAt": "2020-11-23T17:51:18.341Z",
    "uid": "ACDADADASS",
    "eventTypeUid": "YYYYYYY",
    "contact": {
      "email": "example@example.com",
      "name": "John Doe"
    },
    "answers": [{
      "question": "知ったきっかけは？",
      "content": ["SNS", "DM"]
    }]
  }
}

guest_cancelled

ゲストによって予約をキャンセルされたときに生成されるWebhookリクエストです。

{
  "createdAt": "2020-11-23T17:51:19.000000Z",
  "event": "guest_cancelled",
  "object": {
    "status": "cancel",
    "timeZone": "America/New_York",
    "startedAt": "2022-09-01T17:00:00.000Z",
    "endedAt": "2022-09-01T18:00:00.000Z",
    "createdAt": "2020-11-23T17:51:18.341657Z",
    "updatedAt": "2020-11-23T17:51:18.341657Z",
    "uid": "ACDADADASS",
    "eventTypeUid": "YYYYYYY",
    "cancelReason": "仕事の都合のため",
    "cancelledAt": "2022-09-01T17:00:00.000Z",
    "cancelledBy": "guest",
    "contact": {
      "email": "example@example.com",
      "name": "John Doe"
    },
    "answers": [{
      "question": "知ったきっかけは？",
      "content": ["SNS", "DM"]
    }]
  }
}

host_cancelled

ゲストによって予約をキャンセルされたときに生成されるWebhookリクエストです。

{
  "createdAt": "2020-11-23T17:51:19.000000Z",
  "event": "host_cancelled",
  "object": {
    "status": "cancel",
    "timeZone": "America/New_York",
    "startedAt": "2022-09-01T17:00:00.000Z",
    "endedAt": "2022-09-01T18:00:00.000Z",
    "createdAt": "2020-11-23T17:51:18.341Z",
    "updatedAt": "2020-11-23T17:51:18.341Z",
    "uid": "ACDADADASS",
    "eventTypeUid": "YYYYYYY",
    "cancelReason": "仕事の都合のため",
    "cancelledAt": "2022-09-01T17:00:00.000Z",
    "cancelledBy": "host",
    "contact": {
      "email": "example@example.com",
      "name": "John Doe"
    },
    "answers": [{
      "question": "知ったきっかけは？",
      "content": ["SNS", "DM"]
    }]
  }
}

トラッキングについて

Jicooアカウントをお持ちの場合、UTM（Urchin tracking module）パラメータを予約ページのリンクに追加することにより、
webhookで追跡することができます。以下の手順で追跡するためのリンクを構築してください。

1.最初にどのUTMコードをリンクに追加するかを定義します。以下のコードのいずれかを使用することができます。

UTM Source

これは、予約された会議がどのサイトから来たかをラベル付けする場所です。例えば、Twitterでキャンペーンを行っている場合、リンクに "utm_source=twitter"を追加します。

UTM Medium

これは、リンクがどこから来たかをラベル付けする場所です。例えば、SNSでリンクを使用した場合、リンクに「utm_medium=social」を追加することができます。

UTM Campaign

ここで、キャンペーンに名前を付けることができます。多くのリンクを様々な場所に貼っている場合、それぞれをつなぐことができるUTMコードです。例えば、夏のキャンペーンを行った場合、リンクに「utm_campaign=summer%20promotion」と追記することができます。

UTM Content

同じ予約ページへのリンクが複数ある場合、UTM　Contentを使用することで、ゲストがどこをクリックして予約を行っているかを確認することができます。例えば、ウェブサイトのヘッダーにあるリンクには「utm_content=header」、ウェブサイトのフッターにあるリンクには「utm_content=footer」を使用することができます。

UTM Term

特定のキーワードを追跡する方法です。例えば、「予約する」というキーワードでランク付けするために広告費を支払う場合、リンクに「utm_term=booking」を追加する必要があります。

2.使用するUTMコードが決まったら、予約ページリンクの後に「？」を追加して、UTMコードを'&'で区切って追加します。

(例：utm_medium=social&utm_source=facebook)コードにスペースを追加する場合は「%20」を使用します（例：utm_campaign=summer%20promotion）。リンクはこのような感じになります。

https://www.jicoo.com/{予約ページURL}?utm_medium=social&utm_source=twitter&utm_campaign=summer%20promotion

webhookのPOSTリクエストのtrackingに上記のパラメータが設定されます。

"tracking": {
  "utm_campaign": "summer promotion",
  "utm_source": "twitter",
  "utm_medium": "social",
  "utm_content": null,
  "utm_term": null
}

レスポンス

お使いのシステムが、Jicoo Webhookからリクエストを受信したとき、ステータスコード200のレスポンスを返却してください。

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

エンドポイントがステータスコード3xx、4xxまたは5xxのHTTPレスポンスを返却する
システムへの接続がタイムアウトする（タイムアウトのデフォルト値は60秒）
システムへの安全なSSL接続を確立できない

送信が失敗した場合、10秒の間隔を空けて2回retry処理を行います。

1回目: イベント発生時即時にリクエスト
２回目: 1回目のリクエストが上記の条件に当てはまる場合、10秒後に再送信
3回目: ２回目のリクエストが上記の条件に当てはまる場合、10秒後に再送信(３回目のリクエストが失敗したらretryはしない)

注意事項

プライベートなプロジェクトに作成した予約の通知はWebhook作成者がそのプロジェクトの参加者ではない場合通知されません。