Zendeskメッセージングのメッセージ配信Webhookを設定する方法

Webhookを使用すると、Zendeskがリアルタイムの通知エンジンに変わります。アップデートをポーリングする代わりに、Webhookは何かが発生した瞬間にデータをシステムにプッシュします。特にメッセージングの場合、配信Webhookを使用すると、メッセージが実際に顧客に届いたかどうかを追跡できます。WhatsAppやTwilioに引き渡されただけでなく、実際に配信されたかどうかを確認できます。

これは、「送信済み」と「配信済み」が異なるため重要です。メッセージがZendeskから送信されても、キャリアレベルで失敗する可能性があり、配信追跡なしではそれを知ることはありません。または、顧客の電話がオフラインであるために、配信されないままになる可能性もあります。配信Webhookを使用すると、メッセージのライフサイクル全体を可視化できます。

このガイドでは、Zendeskメッセージ配信Webhookを最初から設定する方法を学びます。3つの配信イベントタイプについて説明し、設定をステップごとに説明し、独自の実装に合わせて調整できる動作するコードを提供します。

必要なもの

始める前に、以下を確認してください。

• 管理者アクセス権を持つZendeskアカウント（Webhookの設定には管理者権限が必要です）
• Webhookペイロードを受信するHTTPSエンドポイント（開発サーバーはテストに適しています）
• JSONおよびHTTPの基本的な概念に関する知識
• オプション：テスト用のPostmanやcurlなどのツール

本番環境用に構築する場合は、認証、エラー処理、およびべき等性について検討する必要があります。これらすべてについて触れます。

Zendeskメッセージ配信イベントについて

Zendeskのメッセージングプラットフォームは、3種類の配信イベントを送信します。それぞれが、メッセージがどこにあるかについて異なる情報を提供します。

3つの配信イベントタイプ

イベントタイプ	いつ発生するか	何を伝えるか
conversation:message:delivery:channel	メッセージがチャネルAPIに渡されたとき	チャネル（WhatsApp、Twilioなど）がメッセージを受け入れた
conversation:message:delivery:user	メッセージがユーザーのデバイスに到達したとき	顧客が実際にメッセージを受信した
conversation:message:delivery:failure	配信に失敗したとき	何らかの問題が発生しました。エラーの詳細が含まれています

フローは次のようになります。メッセージを送信すると、最初にチャネルのAPIに到達します。そのAPIがメッセージを受け入れると、delivery:channelイベントが発生します。一部のチャネル（WhatsAppやTwilio経由のSMSなど）では、後でメッセージがデバイスに到達したことを確認するdelivery:userイベントが発生する場合があります。途中で何らかの問題が発生した場合は、特定のエラー情報を含むdelivery:failureが発生します。

isFinalEventフラグは、さらにイベントが発生するかどうかを示します。isFinalEvent: trueの場合、これはそのメッセージに対して受信する最後のWebhookです。falseの場合、チャネルはユーザーレベルの配信確認をサポートしているため、フォローアップを期待してください。

チャネルのサポートは異なります

すべてのチャネルがユーザーへの配信を確認できるわけではありません。Zendeskからメッセージを受信したことのみを確認するものもあります。内訳は次のとおりです。

完全な配信確認（チャネル+ユーザー）を備えたチャネル：

• WhatsApp（ワッツアップ）
• Twilio SMS（トゥイリオSMS）
• MessageBird（メッセージバード）
• iOS SDK、Android SDK、Unity SDK、Web Widget（ウェブウィジェット）

チャネル配信のみのチャネル：

• Facebook Messenger（フェイスブックメッセンジャー）
• Instagram（インスタグラム）
• LINE（ライン）
• Telegram（テレグラム）
• Viber（バイバー）
• WeChat（ウィーチャット）
• X (Twitter)（X（ツイッター））
• Apple Messages for Business（アップルメッセージフォービジネス）

ユーザー確認のないチャネルの場合、delivery:channelイベントにはisFinalEvent: trueが含まれます。これは、それ以上のアップデートがないというシグナルです。

これが実装にとって重要な理由

これらのWebhookの上に分析を構築する場合は、このバリエーションを考慮する必要があります。「配信済み」メトリックは、チャネルによって異なる意味を持ちます。WhatsAppの場合、これはデバイスレベルの確認です。Facebook Messengerの場合、これはFacebookのAPIがメッセージを受け入れたことを意味するだけです。

ステップ1：Zendesk管理センターでWebhookを作成する

最初の配信Webhookの作成について説明しましょう。

まず、管理センター>アプリとインテグレーション> Webhookに移動します。Webhookオプションが表示されない場合は、役割に適切な権限があることを確認してください。詳細については、Zendesk Webhookドキュメントを参照してください。

Webhookを作成をクリックします。いくつかのフィールドを含むフォームが表示されます。

名前：「メッセージ配信トラッカー」や「本番配信イベント」など、わかりやすい名前を付けます。

**エンドポイントURL：**これは、ZendeskがWebhookペイロードをPOSTする場所です。開発の場合、ngrokなどのツールを使用してローカルサーバーを公開できます。本番環境の場合、これはインフラストラクチャ上のHTTPS URLである必要があります。

**HTTPメソッド：**POSTを選択します。配信イベントは常にPOSTを使用します。

**リクエスト形式：**JSONを選択します。

まだ保存しないでください。次のステップでイベントサブスクリプションと認証を設定します。

ステップ2：配信イベントをサブスクライブする

Webhook作成フォームで、イベントサブスクリプションセクションを見つけます。ここでは、どのイベントがWebhookをトリガーするかを指定します。

メッセージ配信追跡の場合、次の3つのイベントをサブスクライブします。

1. conversation:message:delivery:channel
2. conversation:message:delivery:user
3. conversation:message:delivery:failure

必要に応じて追加のイベント（すべてのメッセージのconversation:messageなど）をサブスクライブできますが、特に配信追跡の場合、これら3つが必要です。

イベントフィルタリングオプション：

インテグレーションがスイッチボードの一部である場合、アクティブに管理していない会話のイベントを受信するかどうかを制御できます。deliverStandbyEvents設定はこれをフィルタリングします。ほとんどのインテグレーションは、アクティブな会話のイベントのみを受信するように、これをfalseに設定します。

Webhookを保存します。Zendeskは一意のID（01で始まる）を割り当てます。このIDをコピーします。テストや、トリガーに接続する場合は、これが必要になります。

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

認証のないWebhookはセキュリティリスクです。エンドポイントURLを発見した人は誰でも偽のイベントを送信できます。Zendeskはいくつかの認証方法をサポートしています。

利用可能な認証オプション

方法	最適な用途	仕組み
APIキー	シンプルなインテグレーション	ヘッダーベースのキー検証
基本認証	レガシーシステムとの互換性	Authorizationヘッダーのユーザー名/パスワード
ベアラートークン	最新のAPIインテグレーション	OAuthまたはJWTトークン検証

ほとんどの実装では、APIキー認証はセキュリティとシンプルさの適切なバランスを取ります。

Zendeskでの設定

Webhookフォームで、認証セクションを展開します。希望する方法を選択し、資格情報を入力します。

• APIキーの場合：ヘッダー名（例：X-API-Key）とキー値を指定します
• ベアラートークンの場合：Zendeskに含めるトークンを入力します
• 基本認証の場合：ユーザー名とパスワードを入力します

Webhook署名の検証

Zendeskは、HMAC-SHA256を使用してWebhookに署名できます。これにより、ペイロードが実際には攻撃者ではなくZendeskから送信されたことを確認できます。詳細な実装ガイダンスについては、Zendesk Webhook署名ドキュメントを参照してください。

これを有効にするには、次のことを行う必要があります。

1. 署名シークレットを生成します（Zendeskは署名を有効にするとこれを提供します）
2. エンドポイントでX-Zendesk-Webhook-Signatureヘッダーを確認します
3. シークレットを使用してペイロードのHMAC-SHA256を計算します
4. 署名ヘッダーと比較します

簡単なNode.jsの例を次に示します。

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('base64');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

ステップ4：Webhookエンドポイントを構築する

さあ、楽しい部分です。これらのWebhookを受信するエンドポイントを構築します。

基本的な要件

エンドポイントは次のことを行う必要があります。

• HTTPSを使用する（ZendeskはHTTP URLを拒否します）
• 10秒以内に応答する
• 正常な処理のために2xxステータスコードを返す
• 重複するイベントを正常に処理する（べき等性）

サンプルWebhookレシーバー（Node.js/Express）

最小限でありながら本番環境に対応できるエンドポイントを次に示します。

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhooks/zendesk-delivery', (req, res) => {
  // Acknowledge receipt immediately
  res.status(200).send('OK');

  // Process events asynchronously
  const events = req.body.events || [];

  for (const event of events) {
    handleDeliveryEvent(event);
  }
});

function handleDeliveryEvent(event) {
  const { type, payload } = event;

  switch (type) {
    case 'conversation:message:delivery:channel':
      console.log(`Message ${payload.message.id} delivered to ${payload.destination.type}`);
      break;

    case 'conversation:message:delivery:user':
      console.log(`Message ${payload.message.id} reached user`);
      break;

    case 'conversation:message:delivery:failure':
      console.error(`Message ${payload.message.id} failed:`, payload.error);
      break;
  }
}

app.listen(3000, () => {
  console.log('Webhook endpoint listening on port 3000');
});

この例の重要な点は次のとおりです。

1. 処理前にすぐに応答します（200 OK）
2. イベントを非同期的に処理します
3. 各イベントタイプを個別に処理します
4. ログ/デバッグに関連するIDを抽出します

再試行とべき等性の処理

Zendeskは、エラーに応じて失敗したWebhook（4xx/5xx応答、タイムアウト）を最大3〜5回再試行します。これは、エンドポイントが同じイベントを複数回受信する可能性があることを意味します。

これを処理するには、べき等性を実装します。

const processedEvents = new Set(); // Use Redis in production

function handleDeliveryEvent(event) {
  if (processedEvents.has(event.id)) {
    console.log(`Skipping duplicate event: ${event.id}`);
    return;
  }

  // Process the event...

  processedEvents.add(event.id);
}

本番環境では、Redisまたはデータベースを使用して、処理されたイベントIDをTTL（Time to Live）で追跡し、重複排除ウィンドウがZendeskの再試行動作と一致するようにします。

ステップ5：配信Webhookペイロードについて

これらのWebhookに実際に何が到着するかを分解してみましょう。

一般的なペイロード構造

すべての配信イベントは、このラッパ構造を共有します。

{
  "app": {
    "id": "5fb29b20fee5422428712475"
  },
  "webhook": {
    "id": "5ff5e98b0d0c6d8925594923",
    "version": "v2"
  },
  "events": [
    {
      "id": "5ff7595eafcaab0a685ff889",
      "createdAt": "2021-01-07T18:56:30.666Z",
      "type": "conversation:message:delivery:channel",
      "payload": {
        "conversation": { "id": "2d4fd3d00715d1e64611e248" },
        "user": { "id": "71268330a47f5c4b541fce46" },
        "destination": {
          "type": "whatsapp",
          "integrationId": "5ff75853b1c3000a6ad4f7f5"
        },
        "message": { "id": "5ff7595eb1c3000a6ad4f7fb" },
        "isFinalEvent": false,
        "externalMessages": [
          { "id": "wamid.HBgNNTUxQTk4MDUz5Tg4MRU..." }
        ]
      }
    }
  ]
}

主要なフィールドの説明

フィールド	重要な理由
events[].id	一意のイベントID。重複排除に使用します。
events[].payload.conversation.id	イベントを特定の会話にリンクします。
events[].payload.message.id	このイベントが参照する特定のメッセージ。
events[].payload.destination.type	どのチャネル（whatsapp、twilioなど）。
events[].payload.isFinalEvent	このメッセージに対してさらにイベントが発生するかどうか。
events[].payload.externalMessages	デバッグ用のチャネルのネイティブメッセージID。

失敗イベントの詳細

配信が失敗した場合、ペイロードにはエラーオブジェクトが含まれます。

{
  "error": {
    "code": "bad_request",
    "message": "Message failed to send because more than 24 hours have passed since the customer last replied.",
    "underlyingError": {
      "errors": [{
        "code": 131047,
        "title": "Re-engagement message",
        "message": "Re-engagement message"
      }]
    }
  }
}

underlyingErrorフィールドには、チャネルのAPIからの生のエラーが含まれています。これはデバッグに非常に役立ちます。たとえば、WhatsAppのエラーコードは、メッセージが拒否された理由を正確に示します。

ステップ6：Webhookの実装をテストする

本番環境に移行する前に、すべてが機能することを確認する必要があります。

ZendeskのWebhookテスターを使用する

Webhook構成ページで、Webhookをテストをクリックします。Zendeskはテストペイロードをエンドポイントに送信し、応答を表示します。これは、接続と認証を確認するのに役立ちます。

ただし、テストペイロードは一般的です。実際の配信イベントにはなりません。現実的なテストを行うには、実際のメッセージフローをトリガーする必要があります。

実際のメッセージでテストする

1. Zendeskメッセージングを介してテストメッセージを送信します
2. エンドポイントログで受信Webhookを確認します
3. ペイロード構造が期待どおりであることを確認します
4. イベント処理ロジックが各タイプを正しく処理することを確認します

ユーザー配信をサポートするチャネル（WhatsAppなど）の場合、2つのイベントフローを確認できます。最初のWebhookにはisFinalEvent: falseが含まれている必要があります。2番目（ユーザー配信）にはisFinalEvent: trueが含まれている必要があります。

Webhookアクティビティログの確認

ZendeskはWebhookログを7日間保持します。管理センター>アプリとインテグレーション> Webhookに移動し、Webhookを選択して、アクティビティタブを表示します。これにより、最近の配信、応答コード、およびエラーが表示されます。

予期されるWebhookが表示されない場合は、以下を確認してください。

• Webhookはアクティブですか（一時停止されていませんか）？
• イベントサブスクリプションは正しいですか？
• エンドポイントは2xxステータスコードで応答していますか？

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

慎重に設定しても、問題が発生します。最も一般的な問題とその修正方法を次に示します。

Webhookが起動しない

メッセージが送信されたときにWebhookを受信しない場合：

• Webhookがアクティブであることを確認します（一時停止またはドラフト状態ではありません）
• 正しいイベントタイプがサブスクライブされていることを確認します
• トリガー接続されたWebhookの場合、トリガー条件が満たされていることを確認します
• Webhookアクティビティログで失敗パターンを確認します

認証エラー（401/403）

Zendeskが認証の失敗を報告する場合：

• エンドポイントが正しいヘッダーを確認していることを確認します
• APIキー/トークンが期限切れになっていないことを確認します
• ヘッダー名の大文字と小文字が区別されているかどうかを確認します
• 署名検証を使用している場合は、HMACを正しく計算していることを確認します

タイムアウトとサーキットブレーカー

Zendeskには10秒のタイムアウトがあります。エンドポイントの時間がかかる場合：

• すぐに応答し（200 OK）、非同期的に処理します
• 大量の処理には、メッセージキュー（SQS、RabbitMQなど）を使用します
• 処理時間を監視し、遅い操作を最適化します

サーキットブレーカーは、5分で70％のエラー率または1,000を超えるエラーでトリップします。これが発生した場合、ZendeskはWebhookを一時停止します。根本的な問題を修正し、Webhookを手動で再アクティブ化する必要があります。

配信イベントの欠落

一部のイベントは表示されるが、他のイベントは表示されない場合：

• チャネルサポートマトリックスを確認してください。すべてのチャネルがユーザー配信確認を送信するわけではありません。
• 特にWhatsAppの場合、メッセージが特定の時間枠外で受信された場合、ユーザー配信イベントが遅延または抑制される可能性があります。
• isFinalEventの動作を確認します。チャネルレベルでtrueの場合、ユーザー配信イベントは続きません。

本番環境のベストプラクティス

Webhookが機能したら、これらの本番環境の推奨事項を検討してください。

エラー処理と監視

• デバッグのために、すべてのWebhook受信をイベントIDでログに記録します
• エラー率の上昇に関するアラートを設定します
• エンドポイントの応答時間を監視します
• チャネルごとの配信率を追跡して、問題を早期に発見します

セキュリティ

• 本番環境では常にHTTPSを使用してください
• Webhook署名検証を実装します
• APIキーを定期的にローテーションします
• 機密性の高いペイロードデータをログに記録しないでください

データ保持

配信イベントには、メッセージメタデータが含まれています。以下を検討してください。

• イベントログを保持する期間
• 完全なペイロードを保存するか、キーフィールドのみを保存するか
• メッセージデータに関するコンプライアンス要件（GDPRなど）

ポーリングを使用するか、Webhookを使用するか

Webhookは、リアルタイムのアップデートに最適です。ただし、履歴データが必要な場合や、イベントを見逃した場合は、ポーリングで補足する必要がある場合があります。メッセージAPIのリストは、ギャップを埋めることができます。

eesel AIでメッセージングワークフローを合理化

カスタムWebhookエンドポイントの構築にはエンジニアリング時間が必要です。認証、再試行、べき等性、およびエラーケースを処理する必要があります。次に、これらのイベントの上に実際のビジネスロジックを構築する必要があります。

この複雑さを処理するためにeesel AIを構築しました。Webhookを自分で管理する代わりに、配信追跡が組み込まれたターンキーメッセージング自動化を利用できます。当社のAIチームメイトは、Zendesk（およびFreshdesk、Gorgiasなど）と統合して、会話をエンドツーエンドで処理します。

AI搭載のメッセージングへのより速いパスをお探しの場合は、ZendeskメッセージングWebhookの完全なガイドをご覧ください。オプションを比較する場合は、2025年のZendeskに最適なAIチャットボットの機能と価格の内訳をご覧ください。