Webフック

最終更新日: 2023年04月19日 09:27

Webhookは、特定のイベントが発生するとリアルタイムで通知を他のサービスにプッシュアウトします。

Webhookは、他のサービスから情報を取得するためにリクエストを必要とするAPIとは異なります。APIで接続されているサービスの多くは、各リクエストに15分（またはそれ以上）の間隔を要します。Webhookは、リクエストなしですぐに情報を送信します。

Webhookの使用例

Webhookは、認知度の向上や顧客とのコミュニケーションのために、リアルタイムでの通知が必要な場合に有効です。Webhookは、Pendoで発生したリアルタイムのイベントに基づいて、ビジネス全体のワークフローを推進することができます。たとえば、次のようなことが可能です。

イベント情報をSegment.comなどのプロバイダーに送信し、他のシステムにルーティングする
AWS LambdaやZapierのような他のプラットフォームでワークフローを動かす
Zendesk Sunshineのように、Pendoイベントを使ってCRMプラットフォームにリアルタイムでアップデートを送信する
イベントをサードパーティのSIEMプロバイダーに送信し、リアルタイムで分析する
監査やコンプライアンスのために管理イベントをアーカイブする

Webhooksを使用して、Pendoで何かが起きたときに自動化されたメッセージや情報を他のサービスに送信できます。Webhookで通知をプッシュすることができるイベントは以下のとおりです。

ガイドを表示する
ウェブトラックイベントを受信する
NPSアンケート（表示/提出）
アンケート調査（表示/提出）
アプリ内で訪問者が最初に表示されたとき
アプリ内でアカウントが最初に表示されたとき

要件

投票調査およびNPSのイベントをWebhookで使用するには、Pendo Agentバージョン 2.33.0以降が必要です。

Webhookを設定し、管理するには、Pendoの管理者権限も必要です。

Webhookの種類

Webhookには次の2種類があります。

URL Webhook。Webhook通知を送信するプラットフォームでは、各Webhookに固有のURLが生成されます。Webhookを受け付けるほとんどのプラットフォームが、URLを使用します。
Segment.com Webhook。Segment.comとの連携により、Segment.com Webhookを作成して、Segmentの推奨フォーマットでイベントを送信することができます。

Webhookは通常、URLを介してイベント情報を送信します。

既存のWebhookを表示する

Pendoでアクティブおよび非アクティブなWebhookのリストを表示するには、左側のナビゲーションで［設定（Setting）］>［インテグレーション（Integrations）］に移動し、［Webhooks］タブを選択します。

Webhookの作成

Webhookを作成するには、左側のナビゲーションで［設定］>［インテグレーション］に移動し、［Webhooks］タブを選択します。ここから、次の手順を実行します。

1. ［インテグレーション］ページの右上にある［+ Webhookを追加（+ Add a Webhook）］ボタンを選択します。

2. 次のようなWebhookの詳細を追加します。

- Webhookの送信先や送信されるデータなどがわかる名前
- Webhookの種類（URLまたはSegment.com）
- 書き込みキーまたは URL（選択したWebhookによって異なります）

3. 以下のURL WebhookまたはSegment.com Webhookのいずれかの手順に従ってください。

4. イベントカテゴリーのタイプを選択します。

- すべてのイベントカテゴリーを選択すると、Webhookのすべてのイベントカテゴリーが送信されます。
- 個々のイベントカテゴリーを選択すると、Webhookで送信するイベントカテゴリーを選択できます。

イベントカテゴリーを選択した後、Pendoに追加のフィルタリングはありません。たとえば、イベントカテゴリーに「ガイド」を選択した場合、Pendoはガイド表示イベントごとに通知を送信します。特定のガイドのイベントを表示したい場合は、Webhookの送信先内で追加のフィルタリングを設定する必要があります。

URL Webhookの作成

Pendo Webhookを受け取ったプラットフォームは、Pendoが通知をプッシュするための固有のURLを生成します。WebhookのURLを入手したら、PendoでWebhookの設定を続けます。

1. 送信先URLを追加します。イベントがトリガーされると、このURLに情報が送信されます。

2. ［テスト（Test）］を選択してサンプルのペイロードを送信し、送信先がイベントのペイロードを受け入れるかどうかを検証することができます。

3. ［シークレット（Secret）］フィールドに値を入力して、URLで受信した情報が信頼された正しいソースのものであることを検証します。シークレットには、特殊文字を含む任意の値を使用でき、単純なものからセキュリティプロトコルで要求されるような複雑なものまで設定できます。

WebhookのPOST「X-Pendo-Signature」には、シークレットを鍵としてシリアル化されたメッセージのsha256 HMACに値が設定されます。このフィールドではWebhookの本文が使用されているため、これは各投稿で変わることが予想されます。本文は、送信されるイベントごとに変化します。記事「Webhookのセキュリティ保護」で説明されている、GithubのWebhook処理の経験を踏襲しました。

警告：Webhookのイベント情報には、お客様のインストールやデータのマッピングによって、個人を特定できる情報（PII）が含まれている場合があります。Webhookのテストや有効化を行うときは、信頼できる送信先やサービスを使用するようにしてください。

Segment.com Webhookの作成

Segment.com Webhookには、Segment.comアカウントが必要です。

1.セグメントで、書き込みキーを取得するためのソースとしてPendoを設定します。詳細については、セグメントのPendoソースの記事をご覧ください。

2. セグメントで、［概要（Overview）］>［インストール（Installation）］に移動し、書き込みキーをコピーします。詳細については、セグメントの書き込みキーを特定するの記事をご覧ください。

3. 作成中のPendo Webhookの［書き込みキー（Write Key）］にキーをコピーします。

Webhookの有効化と無効化

Webhookはデフォルトでは無効になっており、データを送信するには有効にする必要があります。

［設定］>［インテグレーション］>［Webhook］で、Webhookの横にあるトグルを使用して、既存のWebhookを有効または無効にします。

Webhookのスライダーが緑色の場合は、データ送信が有効になっています。同じトグルで、トグルを戻してスライダーをグレーアウトさせ、データの送信を停止します。

Webhookの編集と削除

Pendoで既存のWebhookを編集または削除するには、左側のナビゲーションで［設定］>［インテグレーション］に移動し、［Webhooks］タブを選択します。ここで既存のWebhookにカーソルを合わせると、鉛筆（編集）とゴミ箱（削除）のアイコンが表示されます。

鉛筆（編集）アイコンをクリックすると、Webhookの設定画面が表示され、Webhookに変更を加えることができます。

ゴミ箱（削除）アイコンは、この決定を確認するよう求めた後、Webhookを永久に削除します。Webhookの設定を失わずにデータを停止するには、「Webhookの有効化と無効化」で説明しているように、トグルを使用してWebhookを無効にします。

Webhookの応答の例

このセクションでは、以下のWebhookタイプの応答における本文を例示します。

ガイドが表示された
投票とアンケート調査が表示された
投票とアンケート調査が送信された
NPSが表示された
NPSが送信された
訪問者が作成された
アカウントが作成された
トラックイベントを受信した

ガイドが表示された

{
  "app": {
    "id": -323232,
    "name": "test_application",
    "platform": "web"
  },
  "accountId": "Webhook Account",
  "subscription": {
    "id": 4802463602049999,
    "name": "test_application"
  },
  "userAgent": "Mozilla/5.0(Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.164 Safari/537.36",
  "event": "guideDisplayed",
  "properties": {
    "guideId": "Kg92trd4yOzpDb2inI5eTOdcR0U",
    "guideProperties": {
      "createdAt": 1615411012615,
      "createdByUser": {
        "username": "pendo-user@example.com"
      },
      "id": "Kg92trd4yOzpDb2inI5eTOdcR0U",
      "lastUpdatedAt": 1618322253073,
      "lastUpdatedByUser": {
        "username": "pendo-user@example.com"
      },
      "name": "Poll 1 - Test",
      "steps": [
        {
          "id": "UgG7AtWEXNuvHBBcTqSQ8NxGvAU",
          "lastUpdatedAt": 1618322251476,
          "resetAt": 1617633741117,
          "type": "building-block"
        }
      ]
    },
    "guideStepId": "UgG7AtWEXNuvHBBcTqSQ8NxGvAU",
    "language": "en-US"
  },
  "timestamp": 1626803876,
  "visitorId": "Webhook Visitor",
  "uniqueId": "f9610795860d89fe29491846fe297bcc922e460b"

投票とアンケート調査が表示された

{
  "app": {
    "id": -323232,
    "name": "test_application",
    "platform": "web"
  },
  "accountId": "Webhook Account",
  "subscription": {
    "id": 4802463602049999,
    "name": "test_application"
  },
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.164 Safari/537.36",
  "event": "pollDisplayed",
  "properties": {
    "guideId": "Kg92trd4yOzpDb2inI5eTOdcR0U",
    "guideProperties": {
      "createdAt": 1615411012615,
      "createdByUser": {
        "username": "pendo-user@example.com"
      },
      "id": "Kg92trd4yOzpDb2inI5eTOdcR0U",
      "lastUpdatedAt": 1618322253073,
      "lastUpdatedByUser": {
        "username": "pendo-user@example.com"
      },
      "name": "Poll 1 - Test",
      "steps": [
        {
          "id": "UgG7AtWEXNuvHBBcTqSQ8NxGvAU",
          "lastUpdatedAt": 1618322251476,
          "resetAt": 1617633741117,
          "type": "building-block"
        }
      ]
    },
    "guideStepId": "UgG7AtWEXNuvHBBcTqSQ8NxGvAU",
    "language": "en-US"
  },
  "timestamp": 1626803876,
  "visitorId": "Webhook Visitor",
  "uniqueId": "3373ffb08b355be4e53e3816a84a7bcdd4fbc6ed"
}

投票とアンケート調査が送信された

{
  "app": {
    "id": -323232,
    "name": "test_application",
    "platform": "web"
  },
  "accountId": "Webhook Account",
  "subscription": {
    "id": 4802463602049999,
    "name": "test_application"
  },
  "userAgent": "Mozilla/5.0(Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.164 Safari/537.36",
  "event": "pollSubmitted",
  "properties": {
    "guideId": "Kg92trd4yOzpDb2inI5eTOdcR0U",
    "guideProperties": {
      "createdAt": 1615411012615,
      "createdByUser": {
        "username": "pendo-user@example.com"
      },
      "id": "Kg92trd4yOzpDb2inI5eTOdcR0U",
      "lastUpdatedAt": 1618322253073,
      "lastUpdatedByUser": {
        "username": "pendo-user@example.com"
      },
      "name": "Poll 1 - Test",
      "steps": [
        {
          "id": "UgG7AtWEXNuvHBBcTqSQ8NxGvAU",
          "lastUpdatedAt": 1618322251476,
          "resetAt": 1617633741117,
          "type": "building-block"
        }
      ]
    },
    "guideStepId": "UgG7AtWEXNuvHBBcTqSQ8NxGvAU",
    "language": "en-US",
    "pollResponses": [
      {
        "duration": 11964,
        "pollId": "afxd8uayh4u",
        "pollType": "PositiveNegative",
        "response": 1
      },
      {
        "duration": 11964,
        "pollId": "rtzh4txwz4f",
        "pollType": "NumberScale",
        "response": 2
      },
      {
        "duration": 11964,
        "pollId": "pspats0sy5f",
        "pollType": "FreeForm",
        "response": "Open Text Answer"
      },
      {
        "duration": 11964,
        "pollId": "braocb22n4j",
        "pollType": "PickList",
        "response": "Product Manager"
      }
    ]
  },
  "timestamp": 1626803991,
  "visitorId": "Webhook Visitor",
  "uniqueId": "fbd70226173184006adc31b810b93f36bb52ec02"
}

NPSが表示された

{
  "app": {
    "id": -323232,
    "name": "test_application",
    "platform": "web"
  },
  "accountId": "Webhook Account",
  "subscription": {
    "id": 4802463602049999,
    "name": "test_application"
  },
  "userAgent": "Mozilla/5.0(Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.164 Safari/537.36",
  "event": "npsDisplayed",
  "properties": {
    "guideId": "FjHsQ7S8z0ircYxe3vO4GHawvwI",
    "guideProperties": {
      "createdAt": 1591024335185,
      "createdByUser": {
        "username": "pendo-user@example.com"
      },
      "id": "FjHsQ7S8z0ircYxe3vO4GHawvwI",
      "lastUpdatedAt": 1626804377122,
      "lastUpdatedByUser": {
        "username": "pendo-user@example.com"
      },
      "name": "Quarterly NPS",
      "steps": [
        {
          "id": "WkaB4F2droQ5sSqd-FvC7H9coJQ",
          "lastUpdatedAt": 1619546765626,
          "resetAt": 1592592811776,
          "type": ""
        },
        {
          "id": "oFs_eA1lF61Ywsg0js945UcG798",
          "lastUpdatedAt": 1605640318713,
          "resetAt": 1592592811776,
          "type": ""
        }
      ]
    },
    "guideStepId": "WkaB4F2droQ5sSqd-FvC7H9coJQ",
    "language": "en-US"
  },
  "timestamp": 1626804384,
  "visitorId": "Webhook Visitor",
  "uniqueId": "b1f15067d47df50a1207dc2d0ce6171a40f8304e"
}

NPSが送信された

{
  "app": {
    "id": -323232,
    "name": "test_application",
    "platform": "web"
  },
  "accountId": "Webhook Account",
  "subscription": {
    "id": 4802463602049999,
    "name": "test_application"
  },
  "userAgent": "Mozilla/5.0(Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.164 Safari/537.36",
  "event": "npsSubmitted",
  "properties": {
    "guideId": "FjHsQ7S8z0ircYxe3vO4GHawvwI",
    "guideProperties": {
      "createdAt": 1591024335185,
      "createdByUser": {
        "username": "pendo-user@example.com"
      },
      "id": "FjHsQ7S8z0ircYxe3vO4GHawvwI",
      "lastUpdatedAt": 1626804377122,
      "lastUpdatedByUser": {
        "username": "pendo-user@example.com"
      },
      "name": "Quarterly NPS",
      "steps": [
        {
          "id": "WkaB4F2droQ5sSqd-FvC7H9coJQ",
          "lastUpdatedAt": 1619546765626,
          "resetAt": 1592592811776,
          "type": ""
        },
        {
          "id": "oFs_eA1lF61Ywsg0js945UcG798",
          "lastUpdatedAt": 1605640318713,
          "resetAt": 1592592811776,
          "type": ""
        }
      ]
    },
    "guideStepId": "WkaB4F2droQ5sSqd-FvC7H9coJQ",
    "language": "en-US",
    "nps": {
      "rating": 9,
      "reason": "Keep up the great work!",
      "source": "web"
    }
  },
  "timestamp": 1626804431,
  "visitorId": "Webhook Visitor",
  "uniqueId": "ccb0f95474ae8b630ede92f8f8dbac03cddfc1c3"
}

訪問者が作成された

{
  "app": {
    "id": -323232,
    "name": "test_application",
    "platform": "web"
  },
  "accountId": "Webhook Account",
  "subscription": {
    "id": 4802463602049024,
    "name": "test_application"
  },
  "userAgent": "Mozilla/5.0(Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.164 Safari/537.36",
  "event": "visitorCreated",
  "properties": {
    "browserName": "Chrome",
    "browserVersion": "91.0.4472",
    "sampleGroup": 17
  },
  "timestamp": 1626803875,
  "visitorId": "Webhook Visitor",
  "uniqueId": "1a2c20ed531bf920781d7f1449968b772840e36c"

アカウントが作成された

{
  "app": {
    "id": -323232,
    "name": "test_application",
    "platform": "web"
  },
  "accountId": "Webhook Account",
  "subscription": {
    "id": 4802463602049999,
    "name": "test_application"
  },
  "userAgent": "Mozilla/5.0(Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.164 Safari/537.36",
  "event": "accountCreated",
  "properties": {},
  "timestamp": 1626803875,
  "visitorId": "Webhook Visitor",
  "uniqueId": "38993a6dd7ff256c0112528ca44b291255603647"
}

トラックイベントを受信した

{
  "app": {
    "id": -323232,
    "name": "test_application",
    "platform": "web"
  },
  "accountId": "Webhook Account",
  "subscription": {
    "id": 4802463602049999,
    "name": "test_application"
  },
  "userAgent": "Mozilla/5.0(Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.164 Safari/537.36",
  "event": "trackEventReceived",
  "properties": {
    "eventProperties": {
      "fromTier": "basic",
      "toTier": "pro"
    },
    "name": "Account Upgraded",
    "source": "web"
  },
  "timestamp": 1626804144,
  "visitorId": "Webhook Visitor",
  "uniqueId": "75c32838012a8311fba2b902857c2e848d98f457"

よくある質問

タイムアウトエラーが表示されるのはなぜですか？

Webhookは通常、5分の制限を超えるとタイムアウトになります。5分以上かかるクエリはタイムアウトし、408エラーになります。

エラーが発生した場合、Pendoはイベントの送信を再試行しますか？

429エラーまたは500～599の範囲のエラーメッセージを受信した場合、Pendoは最大5回まで再試行します。

APIバルクメタデータエンドポイント経由で訪問者やアカウントが最初に作成された場合、イベントを受信することはできますか？

いいえ、APIで訪問者やアカウントを作成しても、アプリ内で訪問者が特定されるまでWebhookはトリガーされません。

除外された訪問者からのイベントを受信することはできますか？

いいえ。訪問者が除外されている場合、Pendoは宛先にイベントを送信しません。

Webhookの送信先としてSlackを使用できますか？

いいえ。SlackをWebhookの送信先として使用するには、POSTが特定のフォーマットであることが求められます。Zapierなどのツールを使って、Pendoが送信するJSON本文をSlackが期待するフォーマットに変換する必要があります。