Zendesk Webhookペイロード形式：完全な開発者向けガイド

Webhookは、Zendeskアカウントをリアルタイムの通知エンジンに変えます。APIをポーリングして更新を確認する代わりに、Webhookは、チケットが作成されたり、エージェントが優先度を更新したり、顧客がフィードバックを送信したりすると、すぐにデータをシステムにプッシュします。しかし、信頼性の高い統合を構築するには、Zendeskが送信するデータとその構造を正確に理解する必要があります。

このガイドでは、Zendesk Webhookのペイロード形式を根本から分解します。Zendeskが提供する2種類のWebhook、イベントペイロードの正確な構造、Webhookの信頼性を検証する方法、および実践的な実装のヒントについて学びます。カスタム統合を構築する場合でも、Zendeskをサードパーティツールに接続する場合でも、これらのペイロード形式を理解することが不可欠です。

eesel AIでは、インテリジェントな自動化を実現するために、Zendeskやその他のプラットフォームからのWebhookデータを処理しています。ペイロード形式を正しく理解することが、堅牢で安全な統合を構築するための最初のステップです。

Zendesk Webhookの2つのタイプ

Zendeskは、根本的に異なる2つのWebhook接続方法を提供しており、どちらを選択するかによって、ペイロード形式のオプションが決まります。この決定は後で変更できないため、両方のアプローチを事前に理解しておく価値があります。

イベントサブスクライブWebhook

これらのWebhookは、Zendeskシステムイベントに直接サブスクライブします。ユーザーが作成されたり、チケットステータスが変更されたり、組織が更新されたりすると、Zendeskは自動的にWebhookをエンドポイントに送信します。

知っておくべきことは次のとおりです。

• HTTPメソッド： POSTのみ
• リクエスト形式： JSONのみ
• ペイロード構造： Zendeskによって定義された固定スキーマ
• 最適な用途： ユーザー、組織、ヘルプセンター、またはメッセージングアクティビティに関するリアルタイム通知

ペイロードは予測可能です。Zendeskは送信されるデータを制御するため、柔軟性は低下しますが、構成エラーの余地も少なくなります。

トリガーおよび自動化Webhook

これらは、Zendeskのビジネスルール（トリガーおよび自動化）に接続します。チケットの条件に基づいて、Webhookをいつ起動するかを正確に定義します。

主な特徴：

• HTTPメソッド： GET、POST、PUT、PATCH、DELETE
• リクエスト形式： JSON、XML、またはフォームエンコード
• ペイロード構造： Liquidマークアッププレースホルダーを使用して完全にカスタマイズ可能
• 最適な用途： 条件付きロジックを使用したチケットベースのワークフロー

このアプローチにより、ペイロードを完全に制御できます。含めるデータとその形式を決定します。

適切なアプローチの選択

要素	イベントサブスクライブ	トリガー/自動化
柔軟性	低（固定スキーマ）	高（カスタムペイロード）
セットアップの複雑さ	簡単	より複雑
ユースケース	システム全体のイベント	チケット固有のワークフロー
ペイロードサイズ	システム定義	最大256 KB

カスタムロジックでチケットの変更に対応する必要がある場合は、トリガーWebhookを使用します。ユーザーの作成やメッセージングアクティビティなどのより広範なシステムイベントには、イベントサブスクライブWebhookが適しています。

Webhookリクエストの構造

ZendeskからのすべてのWebhookリクエストには、リクエストに関するメタデータを提供する標準のHTTPヘッダーが含まれています。これらのヘッダーを理解することは、ルーティング、ロギング、およびセキュリティ検証にとって重要です。

標準ヘッダー

ヘッダー	説明	例
x-zendesk-account-id	Zendeskアカウント識別子	123456
x-zendesk-webhook-id	このWebhookの一意の識別子	01F1KRFQ6BG29CNWFR60NK5FNY
x-zendesk-webhook-invocation-id	特定の呼び出しID	8350205582
x-zendesk-webhook-signature	検証用のHMAC-SHA256署名	EiqWE3SXTPQpPulBV6OSuuGziIishZNc1VwNZYqZrHU=
x-zendesk-webhook-signature-timestamp	ISO 8601タイムスタンプ	2021-03-25T05:09:27Z

署名ヘッダーはオプションですが、本番環境での統合には推奨されます。これにより、リクエストが実際にZendeskから送信されたことを確認し、リプレイ攻撃を防ぐことができます。

リクエスト構造の違い

イベントサブスクライブWebhookは、常にPOSTとJSONペイロードを使用します。本文には、標準化されたスキーマの完全なイベントデータが含まれています。

トリガーWebhookは、構成によって異なります。GETリクエストにはURLにパラメーターが含まれる場合があり、POSTリクエストには、設定に応じてJSON、XML、またはフォームエンコードされたデータとしてフォーマットされた本文が含まれます。

イベントペイロードの構造と例

イベントサブスクライブWebhookは、すべてのイベントタイプで一貫したJSONスキーマを使用します。構造を理解すると、イベントの解析が簡単になります。

標準イベントスキーマ

すべてのイベントペイロードには、次のトップレベルのプロパティが含まれています。

{
  "type": "zen:event-type:ticket.created",
  "account_id": 12514403,
  "id": "2b24ef10-19d4-4740-93cf-8f98ec4776c0",
  "time": "2099-07-04T05:33:18Z",
  "zendesk_event_version": "2022-06-20",
  "subject": "zen:ticket:12345",
  "detail": { /* リソースの詳細 */ },
  "event": { /* 変更情報 */ }
}

プロパティ	説明
type	イベントタイプ識別子
account_id	ZendeskアカウントID
id	一意のイベントID
time	イベントが発生した時間
zendesk_event_version	スキーマバージョン（現在は「2022-06-20」）
subject	ドメインとリソース識別子
detail	完全なリソースオブジェクト
event	変更された内容（更新イベントの場合）

チケット作成イベント

新しいチケットが作成されると、Zendeskは次のようなペイロードを送信します。

{
  "account_id": 22129848,
  "detail": {
    "actor_id": "8447388090494",
    "assignee_id": "8447388090494",
    "brand_id": "8447346621310",
    "created_at": "2025-01-08T10:12:07Z",
    "description": "最近の注文についてサポートが必要です",
    "external_id": null,
    "form_id": "8646151517822",
    "group_id": "8447320466430",
    "id": "5158",
    "is_public": true,
    "organization_id": "8447346622462",
    "priority": "LOW",
    "requester_id": "8447388090494",
    "status": "OPEN",
    "subject": "注文ヘルプリクエスト",
    "submitter_id": "8447388090494",
    "tags": ["order-help"],
    "type": "TASK",
    "updated_at": "2025-01-08T10:12:07Z",
    "via": { "channel": "web_service" }
  },
  "event": {
    "meta": {
      "sequence": {
        "id": 39313930383633353634323835,
        "position": 1
      }
    }
  },
  "id": "cbe4028c-7239-495d-b020-f22348516046",
  "subject": "zen:ticket:5158",
  "time": "2025-01-08T10:12:07.672717030Z",
  "type": "zen:event-type:ticket.created",
  "zendesk_event_version": "2022-11-06"
}

detailオブジェクトには、完全なチケットレコードが含まれています。作成イベントのeventオブジェクトには、イベントシーケンスに関するメタデータのみが含まれています。

ステータス変更イベント

更新イベントには、変更された内容を示すより詳細なeventオブジェクトが含まれています。

{
  "event": {
    "current": "OPEN",
    "meta": {
      "sequence": {
        "id": 39313930383633353634323835,
        "position": 1
      }
    },
    "previous": "NEW"
  }
}

currentプロパティとpreviousプロパティは、変更前と変更後の値を示しています。ステータス変更の場合、可能な値は、NEW、OPEN、PENDING、HOLD、SOLVED、CLOSED、DELETED、ARCHIVED、およびSCRUBBEDです。

優先度変更イベント

優先度イベントも同じパターンに従います。

{
  "event": {
    "current": "URGENT",
    "meta": { "sequence": { "id": 39313930383633353634323835, "position": 1 } },
    "previous": "NORMAL"
  }
}

優先度の値は、LOW、NORMAL、HIGH、およびURGENTです。

コメント追加イベント

誰かがチケットにコメントを追加した場合：

{
  "event": {
    "comment": {
      "author": {
        "id": "8659716080510",
        "is_staff": false,
        "name": "John Smith"
      },
      "body": "迅速な対応ありがとうございます！",
      "id": "8659716087550",
      "is_public": true
    },
    "meta": { "sequence": { "id": 39313930383633353634323835, "position": 1 } }
  }
}

コメントオブジェクトには、完全なテキスト、作成者情報、および可視性のステータスが含まれています。

タグ変更イベント

タグの更新の場合、Zendeskは追加および削除された内容を示します。

{
  "event": {
    "meta": { "sequence": { "id": 39313930383633353634323835, "position": 1 } },
    "tags_added": ["urgent", "vip"],
    "tags_removed": ["pending-review"]
  }
}

この構造により、完全な配列を比較せずにタグの変更を簡単に追跡できます。

トリガーWebhookペイロードとプレースホルダー

トリガーおよび自動化Webhookを使用すると、Liquidマークアッププレースホルダーを使用してペイロード形式を完全に制御できます。

一般的なプレースホルダー

プレースホルダー	説明
{{ticket.id}}	チケットID
{{ticket.title}}	チケットの件名
{{ticket.description}}	チケットの説明
{{ticket.status}}	現在のステータス
{{ticket.priority}}	優先度レベル
{{ticket.requester.email}}	リクエスターのメール
{{ticket.requester.name}}	リクエスターの名前
{{ticket.assignee.email}}	担当者のメール
{{ticket.group.name}}	グループ名
{{ticket.organization.name}}	組織名
{{ticket.tags}}	カンマ区切りのタグ
{{ticket.created_at}}	作成タイムスタンプ
{{ticket.updated_at}}	最終更新タイムスタンプ
{{current_user.name}}	アクションをトリガーしたユーザー

カスタムJSONペイロードの例

次のようなカスタムペイロードを作成できます。

{
  "event": "ticket_updated",
  "ticket_id": "{{ticket.id}}",
  "ticket_url": "{{ticket.url}}",
  "subject": "{{ticket.title}}",
  "description": "{{ticket.description}}",
  "status": "{{ticket.status}}",
  "priority": "{{ticket.priority}}",
  "requester": {
    "name": "{{ticket.requester.name}}",
    "email": "{{ticket.requester.email}}"
  },
  "assignee": {
    "name": "{{ticket.assignee.name}}",
    "email": "{{ticket.assignee.email}}"
  },
  "tags": "{{ticket.tags}}",
  "updated_by": "{{current_user.name}}"
}

ペイロードサイズの制限

カスタムペイロードの最大サイズは256 KBです。ペイロードがこの制限を超えると、Zendeskはそれを切り捨てます。大きな説明フィールドや多数のカスタムフィールドを含むペイロードに注意する必要があります。

認証とセキュリティ

Webhookエンドポイントを保護することは非常に重要です。Zendeskは、受信リクエストを検証するための複数の認証オプションを提供しています。

署名検証

最も安全な方法は、HMAC-SHA256署名を使用することです。Zendeskはタイムスタンプとリクエスト本文から署名を生成し、サーバーで検証できます。

アルゴリズム： base64(HMACSHA256(TIMESTAMP + BODY))

Node.js検証の例：

const crypto = require("crypto");

const SIGNING_SECRET = "your_webhook_signing_secret";
const SIGNING_SECRET_ALGORITHM = "sha256";

function isValidSignature(signature, body, timestamp) {
  let hmac = crypto.createHmac(SIGNING_SECRET_ALGORITHM, SIGNING_SECRET);
  let sig = hmac.update(timestamp + body).digest("base64");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(sig)
  );
}

Python検証の例：

import hmac
import hashlib
import base64

def verify_signature(payload, signature, timestamp, secret):
    message = timestamp + payload
    computed = base64.b64encode(
        hmac.new(
            secret.encode('utf-8'),
            message.encode('utf-8'),
            hashlib.sha256
        ).digest()
    ).decode('utf-8')
    return hmac.compare_digest(computed, signature)

署名シークレット

各Webhookには一意の署名シークレットがあります。Zendesk Admin CenterでWebhookの詳細ページにある「Reveal secret（シークレットを表示）」をクリックするか、APIでGET /api/v2/webhooks/{id}/signing_secretにアクセスして取得できます。

作成前にWebhookをテストするには、次の静的シークレットを使用します：dGhpc19zZWNyZXRfaXNfZm9yX3Rlc3Rpbmdfb25seQ==

追加の認証方法

署名検証に加えて、Zendeskは以下をサポートしています。

• APIキー認証： APIキーを含むカスタムヘッダーを追加します
• ベーシック認証： ユーザー名とパスワードまたはAPIトークン
• ベアラートークン： OAuthスタイルのトークン認証

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

• 常にHTTPSエンドポイントを使用してください
• 本番環境では署名を検証してください
• リプレイ攻撃を防ぐためにタイムスタンプを検証してください（5分より古いリクエストは拒否します）
• シークレットをコードではなく環境変数に保存してください
• Webhookハンドラーをべき等にしてください（Zendeskが再試行または重複を送信する可能性があります）

テストとトラブルシューティング

Webhookを本番環境にデプロイする前に、信頼性の高いテスト戦略が必要です。

webhook.siteの使用

Webhook.siteは、受信リクエストをキャプチャする無料の一時URLを提供します。これは、開発中に生のWebhookペイロードを検査するのに最適です。ヘッダーと本文の内容をリアルタイムで表示する一意のURLを取得できます。

Zendeskの組み込みテスト

Admin CenterでWebhookを作成または編集するときに、Zendeskはテスト機能を提供します。テストペイロードをエンドポイントに送信して、応答を確認できます。これは、公開前に接続とペイロード形式を検証するのに役立ちます。

一般的なエラーと解決策

エラー	原因	解決策
401 Unauthorized（認証されていません）	認証の失敗	APIキー、トークン、または署名検証を確認します
403 Forbidden（禁止されています）	エンドポイントがリクエストを拒否しました	エンドポイントが構成どおりにPOST/GETを受け入れることを確認します
404 Not Found（見つかりません）	間違ったエンドポイントURL	Webhook URLを再確認します
タイムアウト	エンドポイントが遅すぎます	応答時間を最適化するか、サーバーの負荷を確認します
サーキットブレーカーがトリガーされました	エラーが多すぎます	エンドポイントの問題を修正し、自動リセットを待ちます

再試行の動作

Zendeskは、失敗したWebhookを自動的に再試行します。

• HTTP 409エラー：最大3回の再試行
• 60秒未満のretry-afterヘッダー付きのHTTP 429/503：再試行
• タイムアウト（12秒の制限）：最大5回の再試行

サーキットブレーカーは、5分以内にリクエストの70％が失敗した場合、または1,000を超えるエラーが発生した場合にアクティブになります。Webhookを5秒間一時停止し、1つのリクエストを試行します。成功した場合、通常の操作が再開されます。

Webhookとeesel AIの統合

Webhookは、インテリジェントな処理と組み合わせることで、より強力になります。eesel AIでは、Zendeskやその他のプラットフォームからのWebhookデータを処理することで、チームのワークフローを自動化するのに役立ちます。

Webhookの統合がサポート業務をどのように強化するかを次に示します。

• インテリジェントなトリアージ： チケット作成Webhookを処理して、コンテンツ分析に基づいてチケットを自動的に分類およびルーティングします
• 自動応答： チケットのステータスと優先度の変更に関するWebhookデータを使用して、コンテキストに応じた返信をトリガーします
• データのエンリッチメント： Webhookペイロードを内部データソースと組み合わせて、エージェントに包括的な顧客コンテキストを提供します
• クロスプラットフォームの同期： Webhookを使用して、ZendeskをCRM、在庫、またはその他のビジネスシステムと同期させます

Zendesk統合は、アカウントに直接接続し、過去のチケットとヘルプセンターから学習して、インテリジェントな自動化を提供します。Webhookは、リアルタイムのトリガーとアクションを有効にすることで、この機能を拡張します。

主なポイントとベストプラクティス

信頼性の高いWebhook統合を構築するには、細部に注意を払う必要があります。覚えておくべきことは次のとおりです。

適切なWebhookタイプを選択してください： イベントサブスクライブWebhookはシステム全体の通知に最適ですが、トリガーWebhookはチケット固有のワークフローに柔軟性を提供します。

本番環境で署名を検証してください： HMAC-SHA256署名検証により、リクエストがZendeskから送信され、改ざんされていないことが保証されます。

再試行を適切に処理してください： Zendeskは、失敗したリクエストを再試行したり、重複を送信したりする可能性があります。ハンドラーがべき等になるように設計してください。

Webhookのヘルスを監視してください： アクティビティログとサーキットブレーカーのステータスを使用して、問題を早期に検出します。

十分にテストしてください： webhook.siteなどのツールを使用して、本番環境にデプロイする前にペイロードを検査します。

Zendesk Webhookペイロード形式を理解することは、堅牢な統合を構築するための基礎です。セキュリティ、テスト、およびエラー処理に対する適切なアプローチにより、システムを同期させ、チームに情報を提供し続ける信頼性の高い接続を作成できます。