ZendeskメッセージングWebhookの設定方法：完全ガイド

Webhookは、Zendeskをリアルタイムの通知エンジンへと変貌させます。手動で更新を確認する代わりに、チケットの作成、メッセージの到着、ユーザーのプロフィール更新など、何かが発生した瞬間にWebhookが外部システムにデータをプッシュします。

具体的な活用例は、緊急チケットのSlackアラートから、eesel AIのようなAIツールへのライブ顧客データの提供まで多岐にわたります。このガイドでは、2種類のZendesk Webhook（イベントベースとトリガーベース）の両方について解説し、Conversations APIを介したメッセージング固有の設定、および統合の安全性を保つための認証方法について説明します。

読み終える頃には、サポートワークフローに接続された実用的なWebhookが完成しているはずです。

Zendesk Webhookとは何か、どのように機能するのか？

Webhookは、Zendesk Support、Guide、Gather、またはMessagingで何かが発生したときに、指定されたURLにHTTPリクエストを送信します。システムのためのリアルタイムのプッシュ通知と考えてください。ユーザーが削除されたり、新しいチケットが届いたりすると、Zendeskは関連データを持ってエンドポイントに通知（ピング）を送ります。

一般的なユースケースには以下が含まれます：

• 優先度の高いチケットに対するSlackやTeamsのアラート
• 顧客記録を最新に保つためのCRM同期
• Twilioや8x8などのサービスを介したSMS通知
• ツールが受信メッセージを処理して回答を生成するAI連携

2つのWebhook接続方法

これらを混同しないことが重要です。一度どちらかの方法でWebhookを作成すると、後から変更することはできません。

イベント購読型（Event-subscribed）Webhookは、ユーザーの作成、組織の更新、ヘルプセンター記事の公開、メッセージングのアクティビティなどのZendeskイベントに反応します。これらは常にJSONペイロードを伴うPOSTを使用し、Zendeskがペイロード構造を制御します。

トリガーまたは自動化（Trigger or automation）Webhookは、Supportのビジネスルールに接続されます。チケットが特定の条件を満たしたときに、Webhookが実行されます。HTTPメソッド（GET、POST、PUT、PATCH、DELETE）を完全に制御でき、リクエスト形式（JSON、XML、またはフォームエンコード）をカスタマイズできます。ペイロードには、実行時にZendeskが値を埋め込む {{ticket.id}} のようなプレースホルダーを使用します。

接続タイプ	トリガー条件	HTTPメソッド	ペイロード制御
Zendeskイベント	ユーザー、組織、メッセージング、ヘルプセンターのアクティビティ	POSTのみ	Zendesk定義
トリガー/自動化	チケットの条件	すべてのメソッド	プレースホルダーによるユーザー定義

Zendesk Webhookの設定方法（メッセージングとトリガー）

Webhookの設定には、管理者アクセス権限またはWebhook権限を持つカスタムロールが必要です。ステップバイステップの手順は以下の通りです。

ステップ 1: 管理センターのWebhookセクションにアクセスする

管理センターに移動し、サイドバーの「アプリおよびインテグレーション」をクリックします。サブメニューから「Webhook」を選択します。既存のWebhookのリスト（ある場合）と、新しいWebhookを作成するためのボタンが表示されます。

トライアルアカウントには制限があります：最大10個のWebhook、毎分60回の呼び出しまでです。有料プランではこれらの制限はなくなります。

ステップ 2: 新しいWebhookを作成する

「Webhookを作成」をクリックし、接続方法を選択します：

• Zendeskイベント: メッセージング、ユーザー、組織、またはヘルプセンターのアクティビティに使用します。購読する特定のイベントを選択します。
• トリガーまたは自動化: カスタムペイロードが必要なチケットベースのアクティビティに使用します。

ここでの選択は永続的です。後でトリガーWebhookをイベント購読型Webhookに変換することはできないため、最初に正しい方を選択してください。

ステップ 3: Webhook設定を構成する

基本設定を入力します：

• 名前と説明: チームが各Webhookの役割を理解できるように、「Slack緊急チケットアラート」や「CRM顧客同期」のような分かりやすい名前を付けます。
• エンドポイントURL: 受信サーバーのURL。セキュリティのため、HTTPSを強く推奨します。
• リクエストメソッド: イベント購読型Webhookの場合、これは常にPOSTです。トリガーWebhookの場合は、エンドポイントが期待するものに基づいて選択します。
• リクエスト形式: JSON、XML、またはフォームエンコード（トリガーWebhookのみ）。

HTTPSエンドポイントには、最大5つのカスタムヘッダーを追加することもできます。ヘッダー名には英数字と一部の記号が使用でき、128文字の制限があります。値は最大1,000文字まで設定可能です。

ステップ 4: 認証を設定する

エンドポイントが必要とする認証方法を選択します：

方法	使用場面	設定
なし	テスト中、またはIP許可リストを使用しているエンドポイント	資格情報は不要
APIキー	ヘッダー認証を使用するサードパーティサービス	ヘッダー内の名前/値のペア
基本認証 (Basic Auth)	内部サービスまたはZendesk API呼び出し	ユーザー名とパスワード（Zendeskの場合は {email}/token:{api_token} 形式を使用）
ベアラートークン	OAuth対応サービス	Authorizationヘッダー内のアクセストークン

すべての認証方法でHTTPSを使用する必要があります。カスタムヘッダーに機密性の高い資格情報を入れないでください。代わりに組み込みの認証オプションを使用してください。

ステップ 5: トリガーまたは自動化に接続する

トリガーベースのWebhookの場合、ビジネスルールに接続する必要があります：

1. 管理センターで「オブジェクトとルール」→「ビジネスルール」→「トリガー」に移動します。
2. 新しいトリガーを作成するか、既存のものを編集します。
3. 「アクション」の下で「アクションを追加」をクリックします。
4. 「Webhookに通知」を選択し、ドロップダウンから作成したWebhookを選択します。
5. プレースホルダーを使用してJSONペイロードを定義します。例：

{
  "ticket_id": "{{ticket.id}}",
  "subject": "{{ticket.title}}",
  "status": "{{ticket.status}}",
  "requester_email": "{{ticket.requester.email}}"
}

Zendeskは、リクエストを送信する前にこれらのプレースホルダーを実際の値に置き換えます。ペイロードは256 KB未満である必要があります。

ステップ 6: Webhookをテストする

本番稼働前に、組み込みのテスト機能を使用します：

1. Webhookページから対象のWebhookを開きます。
2. 「Webhookをテスト」をクリックします。
3. サンプルイベントを選択するか、テストデータを入力します。
4. 「テストを送信」をクリックし、レスポンスを確認します。

ステータスコード200は成功を意味します。エラーが発生した場合は、エンドポイントのログを確認してください。一般的な問題には、URLの間違い、無効な認証、または不正な形式のペイロードなどがあります。

ローカル開発の場合、ngrokやHookdeckのようなツールを使用すると、ローカルサーバーにトンネリングする公開URLを作成できます。これにより、本番環境にデプロイせずにWebhookをテストできます。

Conversations APIを使用したZendeskメッセージングWebhookの設定

Zendeskのメッセージングプラットフォーム（Sunshine Conversations）には、リアルタイムメッセージング用の独自のWebhookシステムがあります。これは標準のWebhookとは別のもので、チャットのやり取りに特化して設計されています。

メッセージングWebhookの作成

メッセージングWebhookはインテグレーションに属します。管理センターまたはAPIを通じて作成できます：

1. 管理センターの「アプリおよびインテグレーション」でカスタムインテグレーションを作成します。
2. WebhookのターゲットURLを登録します。
3. 受信するイベント（conversation:message など）を設定します。
4. より詳細なペイロードを得るために、includeFullUser や includeFullSource などの追加オプションを設定します。

メッセージングの主要なWebhookイベント

メッセージングプラットフォームは、いくつかのイベントタイプをサポートしています：

イベント	説明
conversation:message	ユーザーまたはビジネスによって送信されたメッセージ
conversation:read	ユーザーがメッセージを既読にした
conversation:postback	ユーザーがポストバックボタンをクリックした
passthrough:messaging	チャネル固有のパススルーデータ

Webhookペイロードの理解

メッセージが届くと、Webhookペイロードには適切に応答するために必要なすべての情報が含まれます：

{
  "account_id": 21825834,
  "detail": {
    "id": "141"
  },
  "event": {
    "actor": {
      "id": "zd:answerBot",
      "name": "Support Bot",
      "type": "system"
    },
    "conversation_id": "67ab5f53a96f98663935c3f2",
    "message": {
      "body": "こんにちは。本日はどのようなご用件でしょうか？",
      "id": "67ab5f55155becd183e284cb"
    }
  },
  "type": "zen:event-type:messaging_ticket.message_added"
}

主要なフィールドには、会話ID（スレッドの追跡用）、メッセージ内容、およびアクター情報（メッセージがユーザー、エージェント、システムのどれから送信されたか）が含まれます。このデータにより、AIツールは受信メッセージを分析し、文脈に沿った回答を自動的に生成できます。

認証方法とセキュリティのベストプラクティス

セキュリティは重要です。保護されていないWebhookエンドポイントは、顧客データを漏洩させたり、悪意のある攻撃者が偽のリクエストを注入したりすることを許してしまいます。

適切な認証方法の選択

方法	最適な用途	備考
APIキー	サードパーティサービス	シンプルなヘッダーベースの認証
基本認証 (Basic Auth)	内部サービス、Zendesk API呼び出し	{email}/token:{token} 形式を使用
ベアラートークン	OAuth対応サービス	モダンなAPIの標準
なし	テストのみ	本番環境では絶対に使用しない

Webhook署名の検証

セキュリティが重要な統合の場合、Zendeskは署名検証を提供しています。各リクエストには2つのヘッダーが含まれます：

• X-Zendesk-Webhook-Signature: メインの署名
• X-Zendesk-Webhook-Signature-Timestamp: 検証用のタイムスタンプ

検証手順：

1. 受信リクエストから両方のヘッダーを抽出します。
2. タイムスタンプとリクエストボディを連結します。
3. Webhookの署名シークレットを使用してHMAC SHA256ハッシュを作成します。
4. 結果をBase64エンコードします。
5. 署名ヘッダーと比較します。

アルゴリズムは次のようになります： base64(HMACSHA256(TIMESTAMP + BODY))

署名が一致すれば、リクエストは本物です。一致しない場合は拒否してください。

署名シークレットは、管理センターのWebhook設定（「シークレットを表示」をクリック）で確認できます。Webhook作成前のテストには、静的なテスト用シークレット dGhpc19zZWNyZXRfaXNfZm9yX3Rlc3Rpbmdfb25seQ== を使用してください。

セキュリティの推奨事項

• 常にHTTPSエンドポイントを使用する
• 本番環境のWebhookには署名検証を実装する
• Webhookハンドラーをべき等（idempotent）にする（Zendeskが再試行したり、重複を送信したりする可能性があるため）
• 配信失敗がないかWebhookアクティビティログを監視する
• 資格情報をハードコードせず、シークレット管理ツールを使用する

一般的なトラブルシューティング

適切に設定されたWebhookでも失敗することがあります。ここでは、最も一般的な問題の診断と修正方法を紹介します。

接続エラー

エラー	原因	解決策
401/403	無効な資格情報	APIキーまたはトークンを確認し、認証方法がエンドポイントの期待と一致しているか確認する
404	エンドポイントURLの間違い	URLパスとドメインが正しいことを確認する
タイムアウト	エンドポイントの応答が遅い	12秒以内に応答し、データ処理は非同期で行う
SSLエラー	証明書の問題	有効なCA署名付き証明書を使用する（Let's Encryptで問題ありません）

サーキットブレーカーの作動

Zendeskは、エンドポイントが過負荷になるのを防ぐ仕組みを持っています。サーキットブレーカーは以下の場合に作動します：

• 5分以内にリクエストの70%が失敗した場合、または
• 5分以内に1,000件以上のエラーが発生した場合

作動すると、Webhookは5秒間一時停止します。停止後、Zendeskは再試行します。リクエストが成功するとサーキットがリセットされますが、失敗すると再び5秒間停止します。このサイクルはエンドポイントが回復するまで続きます。

5分間のリクエスト数が100件未満の場合はサーキットブレーカーは作動しないため、低ボリュームのWebhookが誤ってロックアウトされることは通常ありません。

デバッグのヒント

• 管理センターのWebhookセクションでアクティビティログを確認する（7日間保持）
• ステータスでログをフィルタリングする： filter[status]=failed
• リクエスト監視ツールを使用して、実際のペイロードを検査する
• ペイロード形式がエンドポイントの期待するものと一致しているか確認する
• Postmanやcurlなどのツールでテストし、問題を切り分ける

再試行の動作

レスポンス	動作
HTTP 409	最大3回まで再試行
HTTP 429/503（retry-after < 60秒）	ヘッダーに従って再試行
タイムアウト（12秒以上）	最大5回まで再試行
その他のエラー	自動再試行なし

ZendeskはWebhookを一度届けるために最善を尽くしますが、重複やイベントの欠落が発生する可能性があります。ハンドラーはべき等になるように設計してください。

eesel AIでWebhook連携を効率化

Webhookの設定は最初のステップに過ぎません。インテリジェントな回答を構築するには、ペイロードの解析、ナレッジベースとの統合、文脈に沿った返信の作成、例外処理など、さらなる開発が必要です。そこで私たちの出番です。

eesel AIはZendeskに接続し、複雑な処理を代行します：

• リアルタイム処理: チケットやメッセージングイベントが発生した瞬間に取り込みます。お客様側でのWebhook開発は不要です。
• 文脈に沿った回答: AIがナレッジベース、過去のチケット、ヘルプセンターを使用して、ブランドボイスに合った返信を生成します。
• 返信以外のアクション: Shopifyでの注文検索、返金処理、チケットフィールドの更新などを、コードなしで設定できます。
• 段階的な導入: 最初はコパイロットモード（エージェントが確認するための下書き作成）から始め、徐々に自律的な回答へと移行できます。

Zendeskでeesel AIを使い始める

設定は数分で完了します：

1. ダッシュボードからZendeskアカウントを接続します。
2. 既存のデータ（過去のチケット、ヘルプセンター記事、マクロ、接続されたドキュメント）で学習させます。
3. モードを選択します：コパイロット（エージェントがAIの下書きを確認）または自律型（AIが直接回答）。
4. 本番稼働前に、過去のチケットでシミュレーションを実行して品質を確認します。

これにより、カスタムのWebhookハンドラーを構築する必要がなくなり、AIを活用したサポート自動化を実現できます。成熟した導入事例では、最大81%の自律的な解決を達成し、2ヶ月未満で投資回収を実現しています。

プラン	月払い	年払い	月間インタラクション数
Team	$299	$239/月	1,000
Business	$799	$639/月	3,000
Custom	お問い合わせ	カスタム	無制限

Businessプランには、自律回答用のAIエージェント、過去のチケット学習、一括シミュレーション機能が含まれています。eesel AIを7日間無料でお試しください。