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の送信先内で追加のフィルタリングを設定する必要があります。
URL Webhookを作成する
Pendo Webhookを受け取ったプラットフォームは、Pendoが通知をプッシュするための固有のURLを生成します。WebhookのURLを入手したら、PendoでWebhookの設定を続けます。
- 送信先URLを追加します。イベントがトリガーされると、このURLに情報が送信されます。
- ［テスト（Test）］を選択してサンプルのペイロードを送信し、送信先がイベントのペイロードを受け入れるかどうかを検証します。
- ［シークレット（Secret）］フィールドに値を入力して、URLで受信した情報が信頼された正しいソースのものであることを検証します。シークレットには、特殊文字を含む任意の値を使用でき、単純なものからセキュリティプロトコルで要求されるような複雑なものまで設定できます。
WebhookのPOST「X-Pendo-Signature」には、シークレットを鍵としてシリアル化されたメッセージのsha256 HMACに値が設定されます。このフィールドではWebhookの本文が使用されているため、これは各投稿で変わることが予想されます。本文は、送信されるイベントごとに変化します。記事「Webhookのセキュリティ保護」で説明されている、GithubのWebhook処理の経験を踏襲しました。
警告：Webhookのイベント情報には、お客様のインストールやデータのマッピングによって、個人を特定できる情報（PII）が含まれている場合があります。Webhookのテストや有効化を行うときは、信頼できる送信先やサービスを使用するようにしてください。
SegmentのWebhookを作成する
SegmentのWebhookにはTwilio Segmentアカウントが必要です。
- セグメントで、書き込みキーを取得するためのソースとしてPendoを設定します。詳細については、セグメントのPendoソースの記事をご覧ください。
- Segmentで、［概要（Overview）］>［インストール（Installation）］に移動し、書き込みキーをコピーします。詳細については、Segmentの書き込みキーを特定するの記事をご覧ください。
- 作成中のPendo Webhookの［書き込みキー（Write Key）］にキーをコピーします。
Webhookのオン/オフを切り替える
Webhookはデフォルトではオフになっており、データを送信するには有効にする必要があります。
［設定］>［インテグレーション］>［Webhooks］で、Webhookの横にあるトグルを使用して、既存のWebhookをオンまたはオフにします。
Webhookのトグルが緑色の場合は、データ送信が有効になっています。同じトグルで、トグルをスライドさせグレーアウトの状態に戻し、データの送信を停止します。
Webhookを編集・削除する
Pendoで既存のWebhookを編集または削除するには、左側のナビゲーションで［設定］>［インテグレーション］に移動し、［Webhooks］タブを選択します。ここで既存のWebhookにカーソルを合わせると、編集（鉛筆）と削除（ゴミ箱）のアイコンが表示されます。
編集（鉛筆）アイコンをクリックすると、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サブスクリプションに含まれていない場合、メールは届きません。
- ［設定（Settings）］>［インテグレーション（Integrations）］>［Webhook］にエラーが記録され、問題があるWebhookを確認できます。Webhookの横に［ログを確認（Review logs）］へのリンクが表示されます。ログの表示、テキストエディターへのコピー、JSONファイルとしてダウンロードを行うことができます
- 詳細な分析を行い、エラーを解決するために、［設定（Settings）］>［エラーログ（Error Log）］にエラーを記録します。システムによって送信される特定のエラーコードについては、こちらのページをご参照ください。
PendoによってオフにされたWebhookは、次の2つの方法で再度オンにすることができます。
- 過去14日以内にWebhookのエラーが発生した場合は、［設定（Settings）］>［インテグレーション（Integrations）］>［Webhook］でエラーログを確認し、問題を特定して解決したことを確認した後、Webhookをオンにすることができます。
- Webhookのエラーログが利用できない場合は、Pendoサポートに問い合わせいただくと、問題を特定して解決することができます。すでに問題を特定している場合は、Pendoサポートに問い合わせいただき、Webhookをオンに戻してください。
よくある質問
エラーが発生した場合、Pendoはイベントの送信を再試行しますか？
429エラーまたは500～599の範囲のエラーメッセージを受信した場合、Pendoは最大5回まで再試行します。
APIバルクメタデータエンドポイント経由で訪問者やアカウントが最初に作成された場合、イベントを受信することはできますか？
いいえ、APIで訪問者やアカウントを作成しても、アプリ内で訪問者が特定されるまでWebhookはトリガーされません。
除外された訪問者からのイベントを受信することはできますか？
いいえ。訪問者が除外されている場合、Pendoは宛先にイベントを送信しません。
Webhookの送信先としてSlackを使用できますか？
いいえ。SlackをWebhookの送信先として使用するには、POSTが特定のフォーマットであることが求められます。Zapierなどのツールを使って、Pendoが送信するJSON本文をSlackが期待するフォーマットに変換する必要があります。