Content last updated 2026-05-26

Webhook

Zendesk webhook に関するドキュメント

このガイドは、GitLab で Zendesk webhook を作成、編集、管理する方法について説明します。管理者は管理者タスクセクションを確認してください。

技術的な詳細

デプロイメントタイプ: Standard
- 注意: 一部の特殊な webhook は Zendesk 内で手動管理されています（そのため ad-hoc デプロイメント方式を使用）
同期リポジトリ
- Zendesk Global
- Zendesk US Government

webhook の理解

webhook とは

Zendesk によると:

webhook は、Zendesk Support のトリガーや自動化が発火するなどのイベントに応じて、指定された URL に HTTP リクエストを送信します。Web 開発者は通常、別のシステムでの動作を呼び出すために webhook を使用します。

簡単に言うと、別のシステムへの HTTP リクエストです。これは GitLab Issue 作成、Slack へのアラートなどに使用できます。

Zendesk での webhook の使用

webhook は Zendesk 内の他の項目（通常は Zendesk のイベント、自動化、トリガー）からのみ使用されます。そのため「直接」使用することはありません。代わりに、トリガーオブジェクトが実行されたときに「間接的に」使用されます。

webhook の管理方法

現在、すべての webhook を Zendesk 自体で管理しています。

管理者以外による webhook の作成

webhook の作成については、機能リクエスト Issue を作成してください（Customer Support Operations チームによる手動対応が必要なため）。

管理者以外による webhook の編集

webhook の変更については、機能リクエスト Issue を作成してください（Customer Support Operations チームによる手動対応が必要なため）。

管理者以外による webhook の削除

webhook の削除については、機能リクエスト Issue を作成してください（Customer Support Operations チームによる手動対応が必要なため）。

管理者タスク

注意

このセクションのすべての項目には Zendesk への Administrator レベルのアクセスが必要です。

Zendesk での webhook の表示

Zendesk インスタンスの管理ダッシュボードに移動します
Apps and integrations > Webhooks > Webhooks に移動します

詳細を確認するには、webhook の名前をクリックします。

webhook のログ表示

webhook のログを表示するには:

webhook ページに移動します
ログを表示する webhook の名前をクリックします
Activity タブをクリックします

そこから、イベントの Invocation ID をクリックして詳細を確認できます。

webhook のテスト

webhook をテストするには:

webhook ページに移動します
ログを表示する webhook の名前をクリックします
ページ右上の Actions リンクをクリックします
Test Webhook をクリックします
ペイロード情報を入力します（実際に使用する内容は webhook 自体によって異なります）
Send test ボタンをクリックします

webhook のサブスクリプション

webhook は実行タイミングを決定するためにサブスクリプションを使用します。webhook サブスクリプションの詳細については、Zendesk のドキュメントをご覧ください。

webhook のリクエスト形式

Zendesk webhook の有効なリクエスト形式は以下の通りです。

JSON（API 値: json）
XML（API 値: xml）
Form encoded（API 値: form_encoded）

webhook の認証

webhook は以下の認証方式を使用できます。

なし（API 値: none）
API Key（API 値: api_key）
Basic 認証（API 値: basic_auth）
Bearer トークン（API 値: bearer_token）

これらの動作の詳細については、Zendesk のドキュメントをご覧ください。

webhook の作成

警告

これは対応するリクエスト Issue（機能リクエスト、管理、バグなど）がある場合のみ実施してください。存在しない場合は、まず作成し（標準プロセスを通してから対応）してください。
webhook を作成しただけでは使用されないことに注意してください。

webhook のエンドポイントやカスタムヘッダーに機密情報が含まれていない場合、同期リポジトリを利用できます。ただし、エンドポイント/カスタムヘッダーに API トークンや秘密鍵などの機密情報が含まれる場合は、Zendesk 自体で作成する必要があります。可能な限り同期リポジトリを使用できるセットアップが常に推奨されます。

同期リポジトリを使用して作成する場合、実際の変更内容はリクエスト自体によります。使用できる開始テンプレートは以下の通りです。

---
name: 'Name of webhook'
previous_name: 'Name of webhook'
description: 'Description of webhook'
status: 'active'
subscriptions:
- 'subscription_to_use'
endpoint: 'URL to use'
http_method: 'Method type to use'
request_format: 'Format of the request'
authentication: null
custom_headers: null

ピアレビューと承認の後、MR をマージできます。次回のデプロイメント時に Zendesk へ同期されます。

Zendesk で手動作成する必要がある場合:

webhook ページに移動します
ページ右上の Create webhook ボタンをクリックします
webhook のタイプを選択します
- Events: ユーザー作成、組織変更などの Zendesk イベントに基づくもの
- Trigger or automation: トリガーまたは自動化経由で実行
ページ右下の Next をクリックします
Events タイプの webhook を作成する場合:
1. 使用するイベントタイプを選択します
2. ページ右下の Next をクリックします
webhook の名前を入力します
webhook の説明を入力します（任意）
エンドポイント URL（つまりペイロードの送信先）を入力します
リクエストメソッドを選択します
リクエスト形式を選択します
使用する認証タイプを入力します
必要な追加ヘッダーを入力します（最大 5 つ）
任意ですが、作成中の webhook をテストする機会があります。正しく動作することを確認するため、これを実施してください。
- ボタンをクリックするとテストプロンプトが表示されます。詳細はwebhook のテストを参照してください。
ページ右下の Create webhook ボタンをクリックします

webhook の編集

警告

これは対応するリクエスト Issue（機能リクエスト、管理、バグなど）がある場合のみ実施してください。存在しない場合は、まず作成し（標準プロセスを通してから対応）してください。
これは webhook を使用するオブジェクトに多くの深刻な下流影響を及ぼす可能性があります。慎重に行ってください。

webhook を編集するには、同期リポジトリで管理されているか、Zendesk で直接管理されているかを判断する必要があります。

同期リポジトリで管理されている場合、同期リポジトリで MR を作成する必要があります。実際の変更内容はリクエスト自体によります。ピアレビューと承認の後、MR をマージできます。次回のデプロイメント時に Zendesk へ同期されます。

Zendesk で直接管理されている場合:

webhook ページに移動します
編集する webhook の名前をクリックします
ページ右上の Actions リンクをクリックします
Edit をクリックします
必要な変更を行います
任意ですが、変更中の webhook をテストする機会があります。正しく動作することを確認するため、これを実施してください。
- ボタンをクリックするとテストプロンプトが表示されます。詳細はwebhook のテストを参照してください。
ページ右下の Update ボタンをクリックします

同期リポジトリ経由で webhook の名前を変更する

webhook の名前を変更する必要がある場合、現在の値を previous_name 属性にコピーし、name 属性を変更します。これにより、同期は対象の webhook を引き続き特定して更新できます。

同期リポジトリ経由で webhook の認証情報を更新する

API キーの更新など、webhook の認証情報を更新する必要がある場合、同期リポジトリ自体で実施する特別な手順があります。

同期リポジトリに移動します
CI/CD 設定に移動します
- Zendesk Global
- Zendesk US Government
TOKENS という名前の file タイプ CI/CD 変数を追加します

CI/CD 変数の内容は、必要な情報を含む JSON ブロック（配列で囲まれたもの）になります。

例として、webhook Do a thing の PRIVATE-TOKEN 値を abc123 に更新する場合、TOKENS CI/CD ファイル変数の内容は以下のようになります。

[
  {
    "name": "Do a thing",
    "PRIVATE-TOKEN": "abc123"
  }
]

これは同期リポジトリが、次回のデプロイメント実行時に webhook Do a thing の PRIVATE-TOKEN 値を更新するために使用します。

このメソッドは、1 回の更新で複数の webhook の認証情報を更新するために使用できます。

[
  {
    "name": "Do a thing",
    "PRIVATE-TOKEN": "abc123"
  },
  {
    "name": "Do another thing",
    "PRIVATE-TOKEN": "def456"
  }
]

デプロイメント実行は、CI/CD ファイル変数 TOKENS を削除して終わります（その情報を使って次回のデプロイメント実行時に不要な強制更新が行われるのを防ぐため）。

webhook の無効化

警告

これは対応するリクエスト Issue（機能リクエスト、管理、バグなど）がある場合のみ実施してください。存在しない場合は、まず作成し（標準プロセスを通してから対応）してください。
これは webhook を使用するオブジェクトに多くの深刻な下流影響を及ぼす可能性があります。慎重に行ってください。

webhook を無効化するには、同期リポジトリで管理されているか、Zendesk で直接管理されているかを判断する必要があります。

同期リポジトリで管理されている場合、同期リポジトリで MR を作成する必要があります。この MR では、対応するトリガーの YAML ファイルに対して以下を行ってください。

ファイルを active から inactive パスに移動します
active 属性の値を false に変更します

ピアレビューと承認の後、MR をマージできます。次回のデプロイメント時に Zendesk へ同期されます。

Zendesk で直接管理されている場合:

webhook ページに移動します
無効化する webhook の名前をクリックします
ページ右上の Actions リンクをクリックします
Deactivate をクリックします
無効化を確認するため、Deactivate webhook をクリックします

webhook の削除

警告

これは対応するリクエスト Issue（機能リクエスト、管理、バグなど）がある場合のみ実施してください。存在しない場合は、まず作成し（標準プロセスを通してから対応）してください。
webhook を削除する場合、同期リポジトリからファイルも削除する必要があるでしょう。

同期リポジトリは削除を実行しないため、Zendesk 自体で実施する必要があります。

Zendesk で webhook を削除するには:

webhook ページに移動します
削除する webhook の名前をクリックします
ページ右上の Actions リンクをクリックします
Delete をクリックします
削除を確認するため、Delete webhook をクリックします

例外デプロイメントの実施

同期リポジトリで管理される webhook の例外デプロイメントを実施するには、対象の webhook 同期プロジェクトに移動し、スケジュールパイプラインページに移動して、同期項目の再生ボタンをクリックします。これにより webhook の同期ジョブがトリガーされます。

監視

技術的な詳細

デプロイメントタイプ: Ad-hoc
同期リポジトリ
- Zendesk Global
- Zendesk US Government

動作の仕組み

GitLab スケジュールパイプラインを使用し、bin/process スクリプトが毎時 15 分（UTC タイムゾーン）に実行されます。このスクリプトは以下を行います。

Zendesk インスタンス内のすべての webhook のリストを取得
各 webhook の過去 1 時間に実行されたすべての実行のリストを取得
実行リストから成功した実行をフィルタリング除外
成功しなかった各実行について Slack に投稿

失敗した実行への対応

Zendesk インスタンスの失敗した実行についてアラートを受け取ったら、次のステップを判断するために実行自体をレビューしてください。実行する具体的なアクションは失敗自体によって異なります。

失敗が Zendesk が使用するペイロードに起因する場合は、バグ Issue を起票
失敗がエンドポイントに起因する場合:
- 以下の方法で実行を再試行:
  - 使用された Request body をコピー
  - カスタムペイロードを使用して、実行に紐づく webhook をテスト
- 再試行が失敗した場合は、バグ Issue を起票

webhook モニターへの変更

警告

これは対応するリクエスト Issue（機能リクエスト、管理、バグなど）がある場合のみ実施してください。存在しない場合は、まず作成し（標準プロセスを通してから対応）してください。

webhook モニターを変更するには、対応するプロジェクトリポジトリで MR を作成する必要があります。実際の変更内容はリクエスト自体によります。

ピアレビューと承認の後、MR をマージできます。これは Ad-hoc デプロイメントタイプであるため、変更は次回のスケジュール実行時に使用されます。

よくある問題とトラブルシューティング

これは必要に応じて項目が追加されていくセクションです。

マージ後に webhook の変更が反映されない

webhook は Standard デプロイメントタイプに従うため、通常のデプロイメントサイクル時（または例外デプロイメントが行われた時）にのみデプロイされます。

最終更新 June 14, 2026: Merge pull request #403 from kyama0/claude/cool-turing-ls6eck (bfd74782)

ページのソースコードを見る - ページの編集 - please contribute.