チケット作成イベントに対するZendesk Webhookの設定方法

Webhookは、Zendeskの自動化ツールの中で最も強力なものの1つです。ヘルプデスクで何かが起こったときに、外部システムにリアルタイム通知を送信できます。顧客が新しいチケットを送信すると、WebhookはSlackでチームに即座に警告したり、CRMを更新したり、独自のアプリケーションでカスタムワークフローをトリガーしたりできます。

チケット作成イベントに対するZendesk Webhookの設定は複雑ではありませんが、途中でいくつかの重要な決定を行う必要があります。このガイドでは、初期設定からテスト、トラブルシューティングまで、プロセス全体を説明します。

必要なもの

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

• Teamプラン以上のZendesk Supportアカウント（WebhookはEssentialプランでは利用できません）
• 管理者アクセスまたはWebhook作成権限を持つカスタムロール
• HTTP POSTリクエストを受信できるエンドポイントURL（Zapierのようなサービス、カスタムAPI、またはWebhookテストサイトなど）
• 認証を使用する場合はAPIトークン（本番環境では推奨）

トライアルアカウントには、Webhookの最大数10個、1分あたりの呼び出し数60回という制限があります。テストには十分ですが、本格的な自動化を行う前にアップグレードすることをお勧めします。

ステップ1：ZendeskでWebhookを作成する

まず、Webhook自体を作成する必要があります。これにより、Zendeskがデータを送信する場所と認証方法が定義されます。

管理センター（Admin Center） → アプリと連携機能（Apps and integrations） → Webhookに移動します。右上の**アクション（Actions）**をクリックし、**Webhookを作成（Create webhook）**を選択します。

設定するいくつかのフィールドを含むフォームが表示されます。

名前と説明（Name and description）: 後で識別できるように、「新規チケット通知（New Ticket Notification）」のような明確な名前をWebhookに付けます。説明はオプションですが、複数のWebhookがある場合に役立ちます。

エンドポイントURL（Endpoint URL）: これは、ZendeskがWebhookデータを送信する場所です。POSTリクエストを受け入れることができる有効なHTTPS URLである必要があります。テストの場合、独自のEndpointを構築せずにペイロードを確認するために、webhook.siteのようなサービスを使用できます。

HTTPメソッド（HTTP method）: イベントサブスクリプションの場合、これはPOSTである必要があります。代わりにトリガーに接続する場合は、Endpointが予期するものに応じて、GET、POST、PUT、PATCH、またはDELETEを選択できます。

リクエスト形式（Request format）: イベントサブスクリプションの場合、これはJSONである必要があります。トリガー接続Webhookは、XMLおよびフォームエンコード形式もサポートしています。

認証（Authentication）: これは本番環境では強く推奨されます。Zendeskは3つの方法をサポートしています。

• APIキー（API key）: キーを含むカスタムヘッダーを追加します
• Basic認証（Basic auth）: ユーザー名とパスワードをbase64でエンコードします
• Bearerトークン（Bearer token）: AuthorizationヘッダーのOAuth 2.0スタイルのトークン

すべて入力したら、下部の**作成（Create）**をクリックします。Webhookが作成されましたが、まだイベントに接続されていません。それが次のステップです。

ステップ2：接続方法を選択する

ここで、重要な決定を下す必要があります。Zendeskは、Webhookをチケットアクティビティに接続する2つの方法を提供しており、後でWebhookを削除して再作成しない限り、これを変更することはできません。

オプションA：イベントサブスクリプション（zen:event-type:ticket.created）

このアプローチでは、WebhookをZendeskのイベントストリームに直接サブスクライブします。チケットが作成されると、Webhookが発火します。

長所：

• 作成されたすべてのチケットに対して発火することが保証されます
• 簡単な設定：トリガーは不要です
• ほぼリアルタイム配信

短所：

• 固定ペイロード構造（送信されるデータをカスタマイズできません）
• フィルタリングなし：スパムを含むすべてのチケットを取得します
• POSTおよびJSONを使用する必要があります

オプションB：トリガー接続Webhook

このアプローチでは、WebhookをZendeskトリガーに接続します。トリガーは、定義した条件に基づいていつ発火するかを決定します。

長所：

• Webhookが発火するタイミングを完全に制御できます（特定のグループ、優先度、タグ）
• Zendeskプレースホルダーを使用したカスタマイズ可能なペイロード
• ノイズ（スパム、テストチケットなど）をフィルタリングできます

短所：

• トリガーの作成と維持が必要です
• わずかに複雑な設定

どちらを選択する必要がありますか？ すべてのチケットが必要で、エンドでフィルタリングしてもかまわない場合は、イベントサブスクリプションを使用します。特定のチケット（優先度の高い問題や特定の組織からのチケットなど）のみが必要な場合は、トリガー接続Webhookを使用します。

ステップ3：トリガーを設定する（トリガー接続Webhookの場合）

オプションBを選択した場合は、Webhookを呼び出すトリガーを作成する必要があります。

管理センター（Admin Center） → オブジェクトとルール（Objects and rules） → **トリガー（Triggers）**に移動します。**トリガーを追加（Add trigger）**をクリックします。

条件を設定します：

少なくとも、チケット（Ticket） | 次の場合（Is） | **作成された（Created）**を追加します

より多くの条件を追加して、Webhookをトリガーするチケットをフィルタリングできます。

• 優先度が高いまたは緊急
• グループは「テクニカルサポート」です
• タグに「エスカレート」が含まれています
• 組織は特定のVIP顧客です

Webhookアクションを追加します：

**アクション（Actions）で、ドロップダウンからアクティブなWebhookに通知（Notify active webhook）**を選択します。ステップ1で作成したWebhookを選択します。

JSONペイロードを設定します：

ここでは、Endpointに送信されるデータを定義します。Zendeskプレースホルダーを使用して、チケットデータを挿入します。

{
  "ticket_id": "{{ticket.id}}",
  "subject": "{{ticket.title}}",
  "description": "{{ticket.description}}",
  "requester_email": "{{ticket.requester.email}}",
  "requester_name": "{{ticket.requester.name}}",
  "priority": "{{ticket.priority}}",
  "status": "{{ticket.status}}",
  "group": "{{ticket.group.name}}",
  "assignee": "{{ticket.assignee.name}}",
  "created_at": "{{ticket.created_at}}",
  "tags": "{{ticket.tags}}",
  "url": "{{ticket.link}}"
}

Zendeskは、Webhookが発火すると、各プレースホルダーを実際のチケットデータに置き換えます。Liquidマークアップを使用して、条件付きロジックを使用することもできます。

重要： 無限ループを防ぐために、無効化条件を追加します。トリガーはチケットが作成されたときに発火し、Webhookがチケットを更新する可能性があるため、トリガーが再び発火するのを防ぐ条件が必要です。一般的なパターンは、Webhook応答でタグを追加し、そのタグを持つチケットを除外することです。

ステップ4：Webhookをテストする

本番環境でWebhookに依存する前に、Webhookが機能することを確認する必要があります。

Webhook設定からテストします：

管理センター（Admin Center） → アプリと連携機能（Apps and integrations） → Webhookに戻ります。Webhookを見つけて、3つのドットメニューをクリックし、**Webhookをテスト（Test webhook）**をクリックします。

Zendeskは、テストペイロードをEndpointに送信します。テストでは、署名検証を確認できるように、静的な署名シークレット（dGhpc19zZWNyZXRfaXNfZm9yX3Rlc3Rpbmdfb25seQ==）を使用します。

実際のチケットでテストします：

Zendeskでテストチケットを作成します。Endpointをチェックして、以下を確認します。

• リクエストが到着しました
• ペイロードに予期されるデータが含まれています
• 認証ヘッダーが存在します（設定されている場合）
• 署名が検証されます（HMACを使用している場合）

Webhookアクティビティログを確認します：

Zendeskは、Webhook呼び出しのログを7日間保持します。これらのログには、Webhook APIからアクセスして、配信ステータス、応答コード、およびエラーを確認できます。

Webhookペイロードを理解する

Zendeskがチケット作成イベントのWebhookを送信する場合、ペイロード構造は接続方法によって異なります。

イベントサブスクライブされたペイロード

直接イベントサブスクリプションの場合、ペイロードは固定スキーマに従います。

{
  "type": "zen:event-type:ticket.created",
  "account_id": 22129848,
  "id": "cbe4028c-7239-495d-b020-f22348516046",
  "time": "2025-01-08T10:12:07.672Z",
  "zendesk_event_version": "2022-11-06",
  "subject": "zen:ticket:5158",
  "detail": {
    "actor_id": "8447388090494",
    "assignee_id": "8447388090494",
    "brand_id": "8447346621310",
    "created_at": "2025-01-08T10:12:07Z",
    "description": "I need help with my order",
    "id": "5158",
    "is_public": true,
    "organization_id": "8447346622462",
    "priority": "LOW",
    "requester_id": "8447388090494",
    "status": "OPEN",
    "subject": "Order help needed",
    "tags": ["order", "help"],
    "via": { "channel": "web_service" }
  },
  "event": { "meta": { "sequence": { "id": 12345, "position": 1 } } }
}

キーフィールドには、チケットID、件名、説明、リクエスターID、優先度、ステータス、および作成タイムスタンプが含まれます。

トリガー接続ペイロード

トリガー接続Webhookの場合、ペイロードはトリガーアクションで定義したものです。構造とコンテンツを完全に制御できます。

認証とセキュリティ

Webhookは機密性の高いチケットデータを伝送できるため、保護することが重要です。

認証方法：

• APIキー（API key）: X-API-Key: your-secret-keyのようなヘッダーを追加します
• Basic認証（Basic auth）: Authorizationヘッダーにbase64エンコードされたusername:password
• Bearerトークン（Bearer token）: OAuth 2.0スタイルのAuthorization: Bearer your-token

HMAC署名検証：

Zendeskは、Webhookの信頼性を検証するためにHMAC-SHA256署名をサポートしています。各Webhookには、一意の署名シークレットがあります。Zendeskは、タイムスタンプとリクエスト本文に対してHMACを計算することにより、すべてのリクエストに署名します。

Endpointは次のことを行う必要があります。

1. x-zendesk-webhook-signatureヘッダーから署名を抽出します
2. x-zendesk-webhook-signature-timestampヘッダーからタイムスタンプを抽出します
3. 署名シークレットを使用して、予期される署名を計算します
4. タイミング攻撃を防ぐために、一定時間比較を使用して比較します

ベストプラクティス：

• 常にHTTPS Endpointを使用してください
• 本番環境で署名を検証します
• 署名シークレットを安全に保管します（コードリポジトリには保管しないでください）
• 重複した配信を処理するために、べき等性を実装します
• 200ステータスを迅速に返します。必要に応じて非同期的に処理します

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

慎重に設定しても、Webhookが期待どおりに機能しない場合があります。最も一般的な問題とその修正方法を次に示します。

Webhookが発火しない：

• トリガー条件を確認します：実際に満たされていますか？
• トリガーがアクティブであることを確認します（無効になっていない）
• 実行を妨げる可能性のある無効化条件を探します
• Webhookステータスが「アクティブ」であることを確認します

Endpointエラー（4xx、5xx応答）：

• 410 Gone：Endpointがエラーを返しました。サーバーログを確認してください
• 429 Too Many Requests：レート制限されています。バックオフを実装します
• 5xxエラー：エンド側のサーバー側の問題

タイムアウトの問題：

Zendeskには、厳密な10秒のタイムアウトがあります。Endpointが10秒以内に応答しない場合、Zendeskはそれを失敗としてマークし、再試行します。Endpointが迅速に応答することを確認し、必要に応じて重い作業を非同期的に処理します。

サーキットブレーカーがトリガーされました：

Webhookが70％のエラー率で失敗するか、5分で1,000以上のエラーが蓄積された場合、Zendeskは自動的にWebhookを無効にします。根本的な問題を修正し、Webhookを手動で再度有効にする必要があります。

アクティビティログが見つからない：

Zendeskは、Webhookアクティビティログを7日間のみ保持します。より長い保持が必要な場合は、独自のインフラストラクチャでWebhookイベントをログに記録する必要があります。

代替手段：Webhookなしでの自動化

Webhookは強力ですが、常に適切なツールであるとは限りません。技術的な設定、継続的なメンテナンス、およびエラー処理が必要です。複雑さを伴わずに自動化が必要な場合は、代替手段があります。

Webhookやカスタム開発を必要とせずにサポート自動化を処理するために、eesel AIを構築しました。Endpointを設定してJSONペイロードを解析する代わりに、eesel AIをZendeskアカウントに接続するだけです。過去のチケットとヘルプセンターの記事から学習し、ルーチンタスクを自動的に処理します。

違いは次のとおりです。

eesel AIを使用すると、次のことができます。

• コンテンツに基づいてチケットを自動タグ付けしてルーティングします
• エージェントの応答を下書きします
• 一般的な質問をエンドツーエンドで処理します
• 複雑な問題を人間にエスカレートします

一番良いところ？ライブになる前に、過去のチケットでテストできます。セットアップを微調整している間、本番環境のワークフローを中断するリスクはありません。

今すぐZendeskワークフローの自動化を開始してください

チケット作成イベントに対するZendesk Webhookを設定すると、新しいサポートリクエストをリアルタイムで把握できます。Slackチャネルへの通知、CRMへの同期、またはカスタムワークフローのトリガーなど、WebhookはZendeskとスタックの残りの部分の間の接着剤を提供します。

プロセスは簡単です。Webhookを作成し、接続方法を選択し、トリガーを設定し（必要な場合）、完全にテストします。信頼性の高い操作を保証するために、認証とエラー処理に注意してください。

Webhookがニーズに対して過剰であると感じる場合は、AI搭載のアプローチがより適切に機能するかどうかを検討してください。eesel AIのようなツールは、Webhookの設定やEndpoint管理なしでチケット処理を自動化できます。eesel AIを無料で試して、Webhookベースのソリューションにコミットする前に、特定のチケットタイプをどのように処理するかを確認できます。

いずれにせよ、目標は同じです。手動のチケット管理に費やす時間を減らし、実際に顧客を支援する時間を増やします。