Zendeskメッセージング会話作成Webhook：完全な実装ガイド

リアルタイム通知は、最新のサポートワークフローのバックボーンです。顧客が会話を開始したとき、誰かが手動で更新を確認するのではなく、システムはすぐにそれを知る必要があります。Webhookはこのギャップを埋めます。

ただし、Zendeskには2つの完全に異なるWebhookシステムがあり、「会話作成」Webhookはほとんどの人が予想するのとは異なる動作をします。このガイドでは、混乱を解消し、AI統合を構築している場合でも、データをCRMに同期している場合でも、通知をSlackにルーティングしている場合でも、Zendeskで会話Webhookを設定して使用する方法を正確に示します。

Zendeskメッセージング会話作成Webhookとは何ですか？

まず、一般的な誤解を解きましょう。人々が「Zendeskメッセージング会話作成Webhook」を検索するとき、通常はSunshine Conversationsメッセージングプラットフォーム（Zendesk Messagingを強化するインフラストラクチャ）のことを考えています。ただし、実際の「会話作成」イベントは、まったく異なるシステムに存在します。

Zendeskには2つのWebhookアーキテクチャがあります。

標準Zendesk Webhookは、チケット、ユーザー、組織、そして会話イベントを処理します。これらは、管理センターのアプリと統合にあります。

メッセージングWebhook（Sunshine Conversations）は、メッセージングプラットフォームを介してリアルタイムチャットメッセージを処理します。これらは個別に構成され、異なるイベントタイプを使用します。

探しているconversation.createdイベントは、メッセージングプラットフォームではなく、標準のWebhookシステムの一部です。これは、メッセージングドキュメントでそれを見つけることを期待する多くの開発者をつまずかせます。

では、このWebhookは実際に何をするのでしょうか？Webウィジェット、モバイルSDK、WhatsApp、またはその他のチャネルから、Zendeskアカウントで新しい会話が開始されると、このWebhookが起動し、すべての会話の詳細を含むペイロードをエンドポイントに送信します。その後、アプリケーションはリアルタイムで反応できます。AIエージェントをトリガーしたり、データウェアハウスにログを記録したり、通知を送信したり、ソースチャネルに基づいて会話をルーティングしたりできます。

メッセージングWebhookを設定するための前提条件

Webhookの構成を開始する前に、以下を確認してください。

• Zendesk管理センターへの管理者アクセス - Webhookを作成し、統合を管理するための権限が必要です。
• ペイロードを受信する準備ができているエンドポイントURL - これは、POSTリクエストを受け入れることができる、公開されているHTTPS URLである必要があります。
• Webhookセキュリティの基本的な理解 - リクエストが実際にZendeskから送信されていることを確認するために、署名を確認する必要があります。
• 再試行と失敗を処理するための計画 - エンドポイントは12秒以内に応答する必要があります。そうしないと、Zendeskは再試行します。

知っておくべき重要な制限事項の1つは、トライアルアカウントは10個のWebhookと1分あたり60回の呼び出しに制限されていることです。トライアルでテストする場合は、それに応じて計画してください。

Zendeskで会話Webhookを作成する方法

Webhookを設定するには、管理センターUIを使用する方法と、APIを使用する方法の2つがあります。UIは1回限りの設定には高速ですが、APIはデプロイメントを自動化したり、複数の環境を管理したりする場合に適しています。

管理センターの使用

ステップ1：Webhookセクションにアクセスする

管理センターに移動し、サイドバーのアプリと統合をクリックします。サブメニューからWebhook > Webhookを選択します。

ステップ2：Webhookを作成する

Webhookを作成をクリックし、接続方法を選択します。会話イベントの場合は、Zendeskイベント（トリガーまたは自動化ではない）を選択します。

接続方法の選択は永続的です。「Zendeskイベント」としてWebhookを作成すると、後でトリガーベースのWebhookに変換することはできません。両方のイベントタイプが必要な場合は、個別のWebhookを作成します。

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

基本的な構成を入力します。

• 名前と説明 - チームが何をするのかわかるように、「新しい会話通知」などの説明的なものを使用します。
• エンドポイントURL - ペイロードを受信するHTTPSエンドポイント。
• リクエストメソッド - POST（イベントサブスクライブWebhookでは固定）。
• リクエスト形式 - JSON（イベントサブスクリプションでも固定）。

ステップ4：会話作成イベントを選択する

イベントサブスクリプションセクションで、ドロップダウンからzen:event-type:conversation.createdを選択します。必要に応じて、複数のイベント（conversation.updatedやconversation.closedなど）をサブスクライブできます。

ステップ5：認証を設定する

認証方法を選択します。

本番環境では、署名検証も有効にする必要があります。Zendeskは各リクエストをHMAC SHA256で署名し、Webhookの署名シークレットに対して署名を検証して、リクエストが正当であることを確認できます。

APIの使用

プログラムによる設定の場合は、Webhook APIを使用します。

curl -X POST https://{subdomain}.zendesk.com/api/v2/webhooks \
  -u {email_address}/token:{api_token} \
  -H "Content-Type:application/json" \
  -d '{
    "webhook": {
      "name": "会話作成Webhook",
      "status": "active",
      "endpoint": "https://your-endpoint.com/webhook",
      "http_method": "POST",
      "request_format": "json",
      "subscriptions": [
        "zen:event-type:conversation.created"
      ],
      "authentication": {
        "type": "bearer_token",
        "data": {
          "token": "YOUR_TOKEN"
        },
        "add_position": "header"
      }
    }
  }'

APIは、監視と更新に使用する一意のWebhook IDを返します。

会話作成Webhookペイロードの理解

会話が作成されると、ZendeskはJSONペイロードをエンドポイントに送信します。以下のようなものが予想されます。

{
  "account_id": 21825834,
  "detail": {
    "id": "141"
  },
  "event": {
    "conversation_id": "67ab5f53a96f98663935c3f2",
    "created_at": "2025-02-11T14:32:05Z",
    "source_channel": "web",
    "participant_count": 1
  },
  "id": "01JQMQH83YNAKWSWJ8B1QH2NSC",
  "subject": "zen:ticket:141",
  "time": "2025-02-11T14:32:05.254571515Z",
  "type": "zen:event-type:conversation.created",
  "zendesk_event_version": "2022-11-06"
}

注意すべき重要なフィールド：

• detail.id - この会話に関連付けられたチケットID
• event.conversation_id - 一意の会話識別子
• event.source_channel - 会話の発生元（web、whatsapp、facebookなど）
• type - このWebhookをトリガーしたイベントタイプ

ペイロード構造は、メッセージングWebhook（conversation:messageタイプを持つネストされたevents配列を使用）とは異なります。標準の会話Webhookは、個々のメッセージではなく、会話ライフサイクルに焦点を当てたフラットな構造を持っています。

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

Webhookは、検証プロセスと同じくらい安全です。エンドポイントは公開されているため、リクエストが実際にZendeskから送信されていることを確認する必要があります。

署名検証

すべてのWebhookリクエストには、次の2つのヘッダーが含まれています。

• X-Zendesk-Webhook-Signature - HMAC SHA256署名
• X-Zendesk-Webhook-Signature-Timestamp - リクエストが送信されたときのUnixタイムスタンプ

リクエストを検証するには：

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

アルゴリズムは次のとおりです：base64(HMACSHA256(TIMESTAMP + "." + BODY))

Webhookの設定ページの「シークレットを表示」をクリックすると、管理センターで署名シークレットを見つけることができます。Webhookを作成する前のテストでは、次の静的テストシークレットを使用します：dGhpc19zZWNyZXRfaXNfZm9yX3Rlc3Rpbmdfb25seQ==

HTTPS要件

本番環境のWebhookには、常にHTTPSエンドポイントを使用してください。セキュリティ上の利点に加えて、カスタムヘッダーや特定の認証方法など、一部の機能はHTTPSでのみ機能します。

べき等性

ZendeskはWebhookを正確に1回配信するように最善を尽くしますが、それを保証することはできません。特に再試行中やサーキットブレーカーがアクティブになった場合、エンドポイントは同じ会話作成イベントを複数回受信する可能性があります。

ハンドラーがべき等になるように設計します。アクションを実行する前に、会話IDをすでに処理したかどうかを確認します。これにより、重複した通知、重複したCRMエントリ、または同じ自動化の2回のトリガーを防ぎます。

アプリケーションでのWebhookイベントの処理

Node.jsで会話Webhookを処理するための基本的なパターンを次に示します。

const crypto = require('crypto');

app.post('/webhook', (req, res) => {
  // 署名を確認
  const signature = req.headers['x-zendesk-webhook-signature'];
  const timestamp = req.headers['x-zendesk-webhook-signature-timestamp'];
  const payload = JSON.stringify(req.body);

  const expectedSignature = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(`${timestamp}.${payload}`)
    .digest('base64');

  if (signature !== expectedSignature) {
    return res.status(401).send('Invalid signature');
  }

  // イベントを非同期的に処理
  const event = req.body;

  if (event.type === 'zen:event-type:conversation.created') {
    // 処理のためにキューに入れる - 応答をブロックしない
    processConversationCreated(event);
  }

  // 再試行を防ぐために迅速に応答
  res.status(200).send('OK');
});

重要な原則：

• 処理する前に署名を確認します
• 200 OKですばやく応答します（12秒以内）
• イベントを非同期的に処理します - ビジネスロジックがHTTP応答をブロックしないようにします
• 重複したイベントを適切に処理します

一般的な統合パターン

AIエージェントのトリガー - 会話が作成されたときに、人間のエージェントにルーティングする前に、AIエージェントが最初に処理する必要があるかどうかを確認します。ルーティングの決定を行うには、ソースチャネル、時刻、または顧客セグメントを確認します。

CRMロギング - レポートと分析のために、CRMで会話の開始をログに記録します。顧客がどこから連絡しているかを理解するために、チャネルソースを含めます。

Slack通知 - 優先度の高い会話が開始されたときにSlackチャネルに通知を送信するか、ソースに基づいて異なるチャネルを異なるSlackチャネルにルーティングします。

AI統合を構築していて、Webhookの開発を完全にスキップしたい場合は、eesel AIがZendeskに直接接続し、カスタムWebhookハンドラーを必要とせずに会話処理を処理します。会話イベントをリッスンし、ナレッジベースに基づいてコンテキストに応じた応答を自動的に生成します。

一般的なWebhookの問題のトラブルシューティング

適切に構成されたWebhookでも失敗する可能性があります。最も一般的な問題を診断して修正する方法を次に示します。

接続エラー

サーキットブレーカーのアクティブ化

エンドポイントがエラーを返し始めると、Zendeskのサーキットブレーカーが作動し、サーバーが過負荷になるのを防ぎます。これは、短い時間枠内でリクエストの大部分が失敗した場合にトリガーされます。

アクティブ化されると、Webhookは一時的に一時停止します。一時停止後、Zendeskは再度試行します。そのリクエストが失敗した場合、サーキットブレーカーは別の一時停止をトリガーします。このサイクルは、リクエストが成功するまで続きます。

**注：**サーキットブレーカーは通常、低ボリュームのWebhookではアクティブにならないため、小規模なテスト環境は通常、偶発的なロックアウトから安全です。

デバッグのヒント

• 管理センターでWebhookアクティビティログを確認します（7日間保持されます）
• ステータスでフィルタリングして、失敗した呼び出しを確認します。APIリクエストに?filter[status]=failedを追加します
• ngrokやHookdeckなどのツールを使用して、開発中に実際のペイロードを検査します
• ペイロード形式がエンドポイントが期待するものと一致していることを確認します。構造は、標準のWebhookとメッセージングWebhookで異なります

再試行動作のリファレンス

eesel AIでWebhook統合を合理化する

カスタムWebhookハンドラーの構築には、かなりの開発時間が必要です。実際のビジネスロジックに取り掛かる前に、署名検証、再試行ロジック、べき等性、およびエラー処理を処理する必要があります。次に、継続的なメンテナンスがあります。ZendeskのAPIの進化に伴う監視、ロギング、および更新です。

目標がWebhookインフラストラクチャではなく、AI搭載のサポート自動化である場合は、より簡単な方法があります。

eesel AIは、Zendeskアカウントに直接接続し、すべてのWebhookの複雑さを処理します。

• リアルタイムの会話処理 - チケットとメッセージングイベントが発生すると、Webhookの開発を必要とせずに取り込みます
• コンテキストに応じたAI応答 - システムは、ナレッジベース、過去のチケット、およびヘルプセンターの記事を使用して、ブランドボイスに一致する返信を生成します
• テキストを超えたアクション - Shopifyで注文を検索したり、払い戻しを処理したり、チケットフィールドを更新したりできます。これらはすべて、コードではなく自然言語の指示を通じて構成されます
• 段階的なロールアウト - エージェントがAIドラフトを確認するコパイロットモードから開始し、自信がついたら自律的な応答に移行します

セットアップには数日ではなく数分かかります。Zendeskアカウントを接続し、既存のデータでトレーニングし、モードを選択します。過去のチケットでシミュレーションを実行して、ライブになる前に品質を確認できます。

eesel AIを使用する成熟したデプロイメントは、最大81％の自律的な解決を達成し、一般的な回収期間は2か月未満です。AI統合のためにカスタムWebhookハンドラーの構築を検討している場合は、最初にeesel AIを7日間無料で試して、ユースケースをカバーできるかどうかを確認してください。

今すぐZendesk会話Webhookの構築を開始する

会話作成Webhookは、リアルタイムのサポート自動化のための強力なツールです。AIエージェントをトリガーしたり、データを外部システムに同期したり、通知をルーティングしたりする場合でも、これらのWebhookを適切に構成して処理する方法を理解することが不可欠です。

重要な区別を覚えておいてください。標準のWebhookは会話ライフサイクルイベント（作成、更新、クローズ）を処理し、メッセージングWebhookはリアルタイムのメッセージフローを処理します。conversation.createdイベントは標準のWebhookシステムに存在し、すべてのチャネルで新しい顧客との会話に対応するためのエントリポイントです。

管理センターUIから始めてペイロード構造に慣れ、自動化する準備ができたらAPIに移行します。最初から署名検証を有効にし、べき等性を考慮して設計し、再試行の嵐を防ぐために迅速に応答します。

インフラストラクチャのオーバーヘッドなしでAI搭載のサポートを構築するチームの場合、eesel AIは、コンテキストに応じたナレッジベースの応答を提供しながら、カスタムWebhookハンドラーの必要性を排除します。いずれにせよ、リアルタイムの会話認識が手の届くところにあります。