Webhookの概要

お知らせ：当社は、お客様により充実したサポート情報を迅速に提供するため、本ページのコンテンツは機械翻訳を用いて日本語に翻訳しています。正確かつ最新のサポート情報をご覧いただくには、本内容の英語版を参照してください。

Webhook は、HTTP コールバックまたはプッシュ API の一種で、サードパーティアプリケーションにリアルタイム通知を自動送信します。これらの通知は、特定のイベントを実行したときに送信されます。

開始する前に、次の点を確認してください。

Webhook を使用するには、HTTP URL を使って自分のアプリケーションとサードパーティツールを連携させる必要があります。この URL は、指定したイベントがトリガーされたときにデータを受信します。いずれかのイベントに関連するアクションが実行されると、そのデータがこの URL に送信されます。
トリガーとは、更新があったときに通知を送信するために選択する一連のイベントです。

利用可能プラン: Premier、Enterprise、Zoho One プラン

Webhook 項目の定義済みセット

項目名	目的	制限事項	必須項目
Webhook 名	Webhook の名前を入力します。	150 文字まで	これは必須項目です。
説明	Webhook の説明を入力します。	20000 文字まで
URL	1. サードパーティアプリケーションの REST API URL を入力します。 2. イベントが実行されたときに HTTP リクエストが送信される URL です。	200 文字まで	これは必須項目です。
タブ	Zoho Sprints では、Webhook はタブごとに設定されます。各タブに対して個別に Webhook を作成できます。		これは必須項目です。
トリガーイベント	1. 各タブには、それぞれに対応したトリガーイベントがあります。 2. 選択したタブに応じて、トリガーイベントを選択します。 3. イベントが実行されると、URL がトリガーされます。		これは必須項目です。
メソッド	イベントで使用する API メソッドを選択します。 - POST - PUT - DELETE - GET		これは必須項目です。
エンティティパラメーター	1. 特定のタブに関連付けられたパラメーターです（projectid、sprintid など）。 2. パラメーターは、標準形式（JSON、XML など、または name = value）またはユーザー定義形式で追加できます。	最大 25 個のパラメーター
カスタムパラメーター	1. 特定のタブに関連付けられていない、汎用的なパラメーターです。 2. カスタムパラメーターは主に、Webhook をトリガーするために使用される API キーや oAuth トークンなどを送信する目的で使用されます。	10 個のパラメーター
ヘッダーパラメーター	HTTP リクエスト内でヘッダーパラメーターを定義することもできます。	10 個のパラメーター
URL プレビュー	1. すべてのパラメーターが付加された Webhook URL のプレビューです。 2. この URL は、サードパーティアプリケーションへの通知に使用されます。	読み取り専用モード

機能の動作

Webhook URL は必ず http://、https://、または www. から始まる必要があります。
各タブごとに作成できる Webhook は 25 個までです。
Webhook は特定のタブにのみ関連付けることができます。一度関連付けると、別のタブに変更することはできません。
失敗した Webhook 通話の詳細および Webhook ログは、直近 5 日分のみ表示できます。
Webhook が 5 回連続で失敗すると、その URL は一時停止されます。再有効化する必要があります。

エラーコード

Webhook が実行されなかった場合、Zoho Sprints では次のエラーコードが表示されます。

HTTP ステータスエラーコード	理由
400 Bad Request	パラメーターが不足しています
401 Unauthorized	無効な oAuth トークンです
402 Request Failed	パラメーターは有効ですが、リクエストが失敗しました
404 Not Found	リクエストされた項目が存在しません
500、502、503、504 Server Errors	サードパーティアプリケーション側で問題が発生しています

例

Zoho Sprints でスプリントが作成されたときに、Zoho Projects にマイルストーンとして追加します。

要件

Zoho Projects のアカウント。
API にアクセスする権限。

手順

1. Zoho Projects でポータルを作成する

Zoho Projects でポータルとプロジェクトを作成します。

2. Zoho Sprints で Webhook を設定する

Webhook 作成フォームの各フィールドに値を入力します。
Webhook 名を入力します。ここでは「Milestone - Sprints」としています。
URL にはサードパーティアプリケーションの URL を入力します。ここでは Zoho Projects がサードパーティアプリケーションです。

Webhook URL は必ず https://、http://、または www. から始まる必要があります。

Webhook URL の説明を入力します。

3. タブとトリガーイベントを選択する

この Webhook の目的は、Zoho Sprints でユーザーがスプリントを作成したときに、それを Zoho Projects のマイルストーンとして追加することです。ここでは「Sprints」タブを使用してアクションを実行します。
タブとして「Sprint」を選択します。
トリガーイベントとして「Sprint Added」を選択します。また、Sprint Update、Sprint 削除、Sprint Start、Sprint Complete などの他のアクションを選択することもできます。
メソッドとして POST を選択します。

4. ユーザー定義形式のパラメーター