このガイドを使って、Finの統合エラーをリアルタイムで自分のシステムに送信します。webhookを追加すると、Finはエラーログに新しいエラーが発生するたびに署名付きPOSTリクエストをあなたのURLに送信し、アラートやチケット、監視にルーティングできます。
注意:エラーログwebhookは、Salesforce、HubSpot、Freshdesk、Zendeskに接続されたFin for platformsワークスペースで利用可能です。
開始前に
webhookを追加、テスト、削除するにはManage apps and integrations権限が必要です。権限がない場合は、WebhookパネルでRequest permissionを選択してください。
エンドポイントはHTTPSで公開されている必要があります。保存時にFinがHEADリクエストを送信して到達可能か確認します。
エンドポイントは7秒以内に2xxステータスコードを返す必要があります。
webhookの追加方法
設定 > エラーログ(Integrationsの下)に移動します。
ページ右上のWebhookをクリックします。
Webhook URLにエンドポイントを入力します。例:
your-server.example.com/error-logs。https://のプレフィックスは自動で追加されます。保存を選択します。URLが検証されると「Webhook saved」が表示されます。
(任意)URLの下に表示されるSigning secretをコピーします。これはFinからのリクエストを検証するために使用します。
Testを選択してテストイベントをエンドポイントに送信します。エンドポイントが正常に応答すると「Test sent」が表示されます。
注意:テストは
pingイベントを送信し、エラーログではありません。エンドポイントが両方のトピックを受け入れることを確認してください(下記例参照)。
Finがwebhookに送信する内容
Finはエラーログに新しいエラーが発生するたびに1回リクエストを送信します。同じ会話で1時間以内に同じエラーが繰り返された場合は、1回だけ記録・送信されることがあります。
各リクエストはJSONボディと以下のヘッダーを含むPOSTです:
Content-Type: application/json
X-Hub-Signature: リクエスト署名(署名の検証方法を参照)。
Intercom-Webhook-Subscription-ID: webhookサブスクリプションのID。
エラーログのペイロード例
エラーの詳細はdata.itemにあります。トピックは常にerror_log.createdです。
{
"type": "notification_event",
"app_id": "abc123de",
"topic": "error_log.created",
"id": "notif_1a2b3c4d",
"created_at": 1762430400,
"data": {
"type": "notification_event_data",
"item": {
"type": "error_log",
"id": "123",
"app_id": "abc123de",
"created_at": 1762430400,
"environment": {
"type": "environment",
"id": "456",
"name": "acme.my.salesforce.com",
"is_production": true
},
"error_code": "INVALID_FIELD",
"error_message": "No such column 'InvalidField' on entity 'Case'",
"request_status": 400,
"request_method": "POST",
"request_path": "/services/data/v58.0/sobjects/Case",
"object_type": "Case",
"api_type": "salesforce_rest_api",
"product_feature": "salesforce_cases",
"integration_type": "salesforce_cases",
"conversation_id": "789"
}
}
}
エラーログのフィールド
id: エラーログエントリーのID。
app_id: あなたのFinワークスペースID。
created_at: エラー発生時刻(秒単位のUnixタイムスタンプ)。
environment: 接続されたhelpdesk環境(Salesforce組織やZendeskサブドメインなど)。nullの場合もあり。
error_code: helpdeskから返されたエラーコード(例:INVALID_FIELD)。
error_message: helpdeskから返されたエラーメッセージ。
request_status、request_method、request_path: 失敗したリクエストのHTTPステータス、メソッド、パス。
object_type: 関連するhelpdeskオブジェクト(例:CaseやKnowledge__kav)。
api_type: Finが呼び出したhelpdesk API(例:salesforce_rest_api、hubspot_rest_api、freshdesk_rest_api、zendesk_rest_api)。
product_feature: 影響を受けたFinの機能(例:salesforce_cases、fin_messenger、knowledge_import、historical_conversations_import)。
integration_type: エラーが発生したFinの統合(例:salesforce_cases、zendesk_tickets)。
conversation_id: 関連するFinの会話(あれば)。nullの場合もあり。
注意:これらのフィールドはエラーログのError detailsパネルに表示される内容と一致します。特定のエラーコードの理解と修正はFin for Salesforce: Fix common integration errorsを参照してください。
重要: error_messageとrequest_pathはhelpdeskから直接取得され、フィールド値やIDなどのレコードデータを含む場合があります。ペイロードは安全に保管してください。
テストペイロード例
{
"type": "notification_event",
"topic": "ping",
"data": {
"type": "notification_event_data",
"item": {
"type": "ping",
"message": "This is a ping notification test message."
}
}
}
署名の検証方法
すべてのリクエストにはX-Hub-Signatureヘッダーが含まれています。これは署名シークレットで署名された生のリクエストボディのHMAC-SHA1で、形式はsha1=<16進ダイジェスト>です。
リクエストを検証するには:
JSON解析前の生のリクエストボディに対して、署名シークレットをキーにHMAC-SHA1を計算します。
16進ダイジェストの前にsha1=を付けます。
X-Hub-Signatureヘッダーと定数時間比較を行い、一致しなければリクエストを拒否します。
例:Rubyの場合
expected = "sha1=" + OpenSSL::HMAC.hexdigest("SHA1", signing_secret, raw_body)
valid = Rack::Utils.secure_compare(expected, request.headers["X-Hub-Signature"])重要:署名シークレットは秘密にしてください。閲覧やコピーはワークスペースのチームメンバー活動ログに記録されます。
配信と再試行
エンドポイントが2xxステータスコードを返すと配信成功とみなされます。Finはリダイレクトを追跡しないため、エンドポイントの最終URLを使用してください。
エンドポイントがタイムアウトまたはエラーを返すと、Finは自動的に再試行します。
エンドポイントが410 Goneを返すと、Finは直ちに送信を停止します。
Finは同じイベントを複数回送信することがあります。重複を無視するにはイベントのトップレベルIDを使用してください。
Finはイベントを順不同で配信することがあります。created_atで並べ替えてください。
Finはエラーごとに1回リクエストを送信するため、helpdeskの障害時には短時間で多数のリクエストが送信されることがあります。迅速に応答し、イベントをバックグラウンドで処理してください。
webhookのステータスメッセージ
配信が失敗している場合、Webhookパネルに以下のメッセージが表示されます:
一時停止中: 「エンドポイントがエラーを返しているため、配信が一時停止されています。自動的に再試行します。」 問題が一時的なら対応不要です。
停止中: 「エンドポイントがエラーを返し続けているため、配信が停止されています。」 エンドポイントを修正し、再度保存を選択して再接続してください。
無効化: 「エンドポイントが410 Goneを返したため、配信が停止されました。」 再接続するには再度保存を選択してください。
Finによる停止: 「Finはこのwebhookへの配信を停止しました。」 再開するにはサポートに連絡してください。
webhookの削除方法
設定 > エラーログに移動し、Webhookを選択します。
URLの横にあるゴミ箱アイコンを選択します。
確認のためRemove webhookを選択します。
FinはそのURLへの新しいエラーログ送信を停止します。既に送信中のものは届く場合があります。いつでもwebhookを再追加できます。再追加すると新しい署名シークレットが作成されるため、エンドポイントで更新してください。
よくある質問
複数のURLにエラーログを送信できますか?
複数のURLにエラーログを送信できますか?
まだできません。ワークスペースごとに1つのエラーログwebhookのみです。
送信するエラーを選べますか?
送信するエラーを選べますか?
いいえ。Finはエラーログに新しく現れたすべてのエラーを送信します。自分のシステムでproduct_feature、api_type、error_codeなどのフィルターを使えます。
webhook追加時に過去のエラーも送信されますか?
webhook追加時に過去のエラーも送信されますか?
いいえ。webhook保存後に記録されたエラーのみ送信されます。
テストでエラーログが送信されなかったのはなぜですか?
テストでエラーログが送信されなかったのはなぜですか?
Testボタンはエンドポイントの到達確認のためにpingイベントを送信します。実際のエラーログはerror_log.createdトピックを使用します。
署名シークレットを変更または再生成できますか?
署名シークレットを変更または再生成できますか?
webhook設定中はシークレットは変わりません。新しいシークレットが必要な場合は、webhookを削除して再追加してください。

