Webフック

最終更新日:

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

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

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

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

Webhookの使用例

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

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

前提条件

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

Webhookを設定し、管理するには、Pendoの管理者権限も必要です。詳細については、役割と権限を参照してください。

Webhookの種類

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

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

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

既存のWebhookを表示する

Pendoでアクティブおよび非アクティブなWebhookのリストを表示するには、左側のメニューで[設定(Setting)]>[インテグレーション(Integrations)]に移動し、[Webhooks]タブを選択します。

Webhookを作成する

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

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

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

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

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

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

    • [すべてのイベントカテゴリー(All event categories)]を選択すると、Webhookのすべてのイベントカテゴリーが送信されます。
    • [個々のイベントカテゴリー(Individual event categories)]を選択すると、Webhookで送信するイベントカテゴリーを選択できます。

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

mceclip0.png

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処理の経験を踏襲しました。

urlwh.png

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

SegmentのWebhookを作成する

SegmentのWebhookにはTwilio Segmentアカウントが必要です。

  1. セグメントで、書き込みキーを取得するためのソースとしてPendoを設定します。詳細については、セグメントのPendoソースの記事をご覧ください。
  2. Segmentで、[概要(Overview)]>[インストール(Installation)]に移動し、書き込みキーをコピーします。詳細については、Segmentの書き込みキーを特定するの記事をご覧ください。
  3. 作成中のPendo Webhookの[書き込みキー(Write Key)]にキーをコピーします。

SegmentWH.png

Webhookのオン/オフを切り替える

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

[設定]>[インテグレーション]>[Webhooks]で、Webhookの横にあるトグルを使用して、既存のWebhookをオンまたはオフにします。

Enable webhook.png

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

Webhookを編集・削除する

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

Edit or delete a webhook.png

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

削除(ゴミ箱)アイコンをクリックすると削除の確認メッセージが表示され、確定するとWebhookは永久に削除されます。Webhookの設定を失わずにデータを停止するには、Webhookのオン/オフを切り替えるで説明しているように、トグルを使用してWebhookを無効にしてください。

Webhookの応答の例

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

ガイドが表示された

{
  "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エラーになります。

Webhookエラー処理

PendoはWebhookのエラー率を継続的に監視しています。Webhookのデリバリーが繰り返し失敗した場合、Pendoは次のように対処します。

  • 対応するWebhookを自動的にオフにします。これは、さらなるデリバリーの失敗を防ぎ、エラー率が高いWebhookが原因で発生する可能性のある中断を軽減するためです。
  • Webhookの所有者(通常はWebhookの作成者)にメール通知を送信します。Webhookの所有者がPendoサブスクリプションに含まれていない場合、メールは届きません。
  • 詳細な分析と解決のために、[設定]>[エラーログ(Error Log)]にエラーを記録します。システムによって送信される特定のエラーコードについては、このページを参照してください。

問題を解決するために受信リソースまたはWebhook定義を変更しないと、多数のエラーが引き続き生成され、自動化によってWebhookが自動的にオフに戻される可能性があります。

この事態を回避するため、 1つ以上のWebhookがオフになると、[設定(Settings)]>[インテグレーション(Integrations)]Webhookページの上部にアラートが表示されます。このアラートが表示されたら、Pendoサポートに連絡して問題の特定と解決に取りかかってください。すでに問題を特定して解決している場合は、Pendoサポートに連絡してWebhookをオンに戻してください。

よくある質問

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

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

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

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

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

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

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

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

 

この記事は役に立ちましたか?
10人中4人がこの記事が役に立ったと言っています