Webhookについて

Webhookについて

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

Webhookは、外部アプリケーションにリアルタイムの通知を自動送信するHTTPコールバックまたはプッシュAPIです。これらの通知は、指定した一連のイベントを実行すると送信されます。

 

利用を開始する前に、以下の点を確認してください：
  1. Webhookの利用を開始するには、HTTP URLを使用してアプリケーションと外部ツールを連携する必要があります。このURLは、指定した一連のイベントが実行されるとデータを受信します。いずれかのイベントに関連する操作が実行されると、データがURLに送信されます。
  2. 実行条件とは、更新時に通知を送信するために選択するイベントの組み合わせです。
情報利用可能なプラン：プレミア、エンタープライズ、Zoho One

Webhookの設定項目
  

項目名

用途

制限

必須項目

［Webhook名］

Webhook名を入力します。

150文字

必須項目です。

［説明］

Webhookの説明を入力します。

20,000文字

 

［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など、または名前=値）か、ユーザー定義の形式でパラメーターを追加します。

 

25個のパラメーター

 

カスタムパラメーター

 

1. 特定のタブに関連付けられていない、全体で使用するパラメーターです。

 

2. カスタムパラメーターは、主にWebhookの実行に使用するAPIキーやOAuthトークンなどの送信に使用します。

 

10個のパラメーター

 

ヘッダーパラメーター

 

HTTP要求にヘッダーパラメーターを定義することもできます。

 

10個のパラメーター

 

URLのプレビュー

 

1. すべてのパラメーターが付加されたWebhookのURLのプレビューです。

 

2. このURLは、外部アプリケーションへの通知に使用します。

 

読み取り専用モード

 

 

 

機能の動作

  1. WebhookのURLは、必ずhttp://、https://、またはwww.で始まる必要があります。
  2. 各タブに作成できるWebhookは25件までです。
  3. Webhookを関連付けられるのは、1つのタブのみです。一度関連付けると、別のタブに関連付けることはできません。
  4. 失敗したWebhook呼び出しの詳細とWebhookのログは、過去5日分のみ表示できます。
  5. Webhookの実行が5回連続で失敗すると、URLが無効になります。再度有効にする必要があります。

エラーコード

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

 

HTTPステータスエラーコード

原因

400 不正な要求

パラメーターが不足しています

401 認証エラー

OAuthトークンが無効です

402 要求の失敗

パラメーターは有効ですが、要求に失敗しました

404 見つかりません

要求された対象が存在しません

500、502、503、504 サーバーエラー

外部アプリケーションに問題があります

 

例

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

必要条件

  1. Zoho Projectsのアカウント。
  2. APIへのアクセス権限。

 

手順

 

1. Zoho Projectsでのポータルの作成
Zoho Projectsでポータルとプロジェクトを作成します。
 
2. Zoho SprintsでのWebhookの設定
  1. Webhookの作成フォームの各項目に値を入力します。
  2. Webhook名を入力します。こちらの例では、「マイルストーン - スプリント」という名前を付けています。
  3. URLには、外部アプリケーションのURLを入力します。こちらの例では、Zoho Projectsが外部アプリケーションに該当します。


  1. WebhookのURLは、必ずhttps://、http://、またはwww.で始まる必要があります。
  1. WebhookのURLの説明を入力します。
3. タブと実行条件となるイベントの選択
  1. このWebhookの目的は、Zoho Sprintsで作成されたスプリントをZoho Projectsにマイルストーンとして追加することです。こちらの操作では、［スプリント］タブを使用します。
  2. タブとして［スプリント］を選択します。
  3. 実行条件となるイベントとして「スプリントの追加」を選択します。「スプリントの更新」、「スプリントの削除」、「スプリントの開始」、「スプリントの完了」など、他の操作も選択できます。
  4. メソッドとして「POST」を選択します。

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


情報
パラメーター名：sprintObject
パラメーター値：
{sprintName=${Sprint.SprintName},
sprintId= ${Sprint.SprintId},
sprintNumber = ${Sprint.SprintNumber}}
 
カスタムパラメーター（名前 = 値）
apiKey = <api_key>
authToken = <auth_token>

5.スプリントの作成と連携のテスト

プロジェクトにサンプルのスプリントを追加して、連携をテストします。設定したパラメーターを使用してWebhookのURLが実行され、Zoho Projectsにサンプルのマイルストーンが追加されます。