Webhook

Webhook

Webhookは、 Zoho Projects から他社アプリへの自動化HTTP通知を容易にする開発者向け機能です。Webhookを使用して、自分のHTTP URLを設定して、個別の業務ルールに関連付けることで、課題に関連するすべての通知やデータ送信処理を自動化できます。Webhookについての詳細は、 WebHooks.org をご参照ください。

利用条件：エンタープライズプラン（最新）

Webhookの設定

  1. 画面右上の  アイコンをクリックします。
  2. ［課題管理］→［Webhook］ の順に移動します。
  3. ［Webhookの追加］ をクリックします。 
  4. ［Webhook］ ページで、必要なパラメーターをすべて入力します。  
  5. ［保存］  をクリックします。 



Webhook設定項目一覧 

項目名
詳細
データの種類
制限事項
名前

Webhook名を入力します。

テキスト

100文字

通知先のURL

外部アプリ/サービスのREST APIのURLを入力します。

URL
1,000文字
メソッド

APIメソッドの種類（POSTまたはGET）を選択します。初期設定では、POSTメソッドが選択されています。

ラジオボタン
-
独自のパラメーターの追加
  • 2つの方法でパラメーターを追加：標準フォーマット、ユーザー定義フォーマット（xml、json等）のいずれか
  • パラメーター名 を入力します。 さらに、課題の項目から選択した、対応するパラメーター値を入力します。
  • これらのパラメーターは、他サービスと連携してWebhookを実行する際に重要です。
テキスト
3,000文字
独自のパラメーターの追加
  • パラメーター名と対応するWebhookの値を入力します。
  • このキーと値のペアは、主に認証トークン、APIキーなどを送信する際に使用します。
テキスト
3,000文字
URLのプレビュー

他社アプリに通知する、完全なWebhook用URLを表示します。

表示専用
表示専用

業務ルールへのWebhookの関連付け

  1. ［業務ルール］ で、 ［ルールの詳細］→［条件］→［ 処理 ］ を選択します。 
  2. ［処理］で、［Webhookの呼び出し］をクリックします。
  3. アイコンをクリックして、業務ルールに新しいWebhookを作成するか、アイコンをクリックして既存のWebhookを呼び出します。
     


  4. ［ ルールの保存 ］ をクリックします。

業務ルールの設定についての 詳細はこちら をご参照ください。


Webhook連携のテスト

  1. 業務ルールの条件に応じて、Zoho Projectsにテストデータを追加します。
  2. 連携するアプリケーションで、Webhook通知経由でZoho Projectsから受信した更新やデータを確認します。
  3. エラーが発生したり、データの不一致が発生したりした場合は、Zoho ProjectsのWebhookの設定を修正します。
  4. Zoho Projectsからアプリケーションへ、期待する結果を得られるまでテストを続けます。 
Webhookは、 課題関連のパラメーター （課題の件名、ステータス、担当者など）と カスタムパラメーター の両方に対応しています。 

既知の制限事項

  • Webhookに対して、 10件の課題関連のパラメーター と 5件のカスタムパラメーター のみ追加できます。
  • ユーザー定義フォーマット（xml、jsonなど）に対して、1件の課題関連パラメーターのみ追加できます。
    • ユーザー定義フォーマットの課題関連のパラメーターの例： <issue-data><title>${Issue.IssueTitle}</title><key>${Issue.IssueKey}</key></issue-data>
  • Webhookは、業務ルールを介してのみ実行されます。つまり、業務ルールが実行された時に、関連付けられたWebhookが呼び出されます。
  • 複数の業務ルールを同じWebhookに関連付けられますが、業務ルールに関連付けられるWebhookは1件のみです。
  • 許可されているWebhookの呼び出し数の上限は、1日あたり最大1,000回です。
  • 失敗したWebhookの実行は、再試行されません。
  • Webhookの呼び出しが10回連続して失敗すると、Webhookは無効になります。
  • 一日のWebhookの呼び出しの閾値に達した場合や、Webhookが連続で失敗したことにより無効になった場合は、メール通知は送信されません。
  • Webhookの失敗は記録され、 ［ Webhookのエラー ］ ページで、 直近の100回の失敗 の履歴が表示されます。 
     


エラーコード

Webhookの実行に失敗した場合、Zoho Projectsで次のいずれかのエラーメッセージが表示されます： 

HTTPステータスコード

  • 400 Bad Request：必要なパラメーターがありません。
  • 401 Unauthorized：無効な認証トークンです。
  • 402 Request Failed：パラメーターは有効ですが、リクエストに失敗しました。
  • 404 Not Found：リクエストした項目が存在しません。
  • 500, 502, 503, 504 Server errors：他社アプリで問題が発生しました。
  • Error Code 1：一時的にAPIサーバーに接続できませんでした。APIサーバーのログとファイアーウォールの設定で、Zoho Projectsからのリクエストを確認してください。

独自のエラー

  • Internal process failure：Webhookの処理中にエラーが発生したため、Webhookが実行されません。
  • Day limit reached：一日の上限に達しました。

利用例

プロジェクト担当者にSMS通知を送信する。 

目的

Webhookを業務ルールに関連付けることで、課題管理で課題を 「 致命的 」 とした場合に、課題の件名をつけてSMSをプロジェクト担当者に送信できます。

前提条件

  • SMSサービスのアカウントがある
  • 業務ルールとWebhookへのアクセス権限がある

操作手順

手順1：SMSサービスのアカウントの作成

SMSサービスでアカウントを作成し、Webhookの設定に必要な以下の情報を取得します。

  • API URL
  • ユーザー名
  • パスワード
  • API ID  

現在、Zohoでは、次のSMSサービスと提携しています：

  1. Bulk SMS
  2. Clickatell
  3. Screen Magic
  4. Valueleaf
  5. Solutions Infini

上記のサービスから、SMSクレジットを購入して、APIの詳細を取得できます。

手順2：Webhookの設定

Webhookページで、以下の詳細を入力します：

通知先のURL：

  1. http://<IP Address>/smsgateway/post - POSTメソッド  

ユーザー定義フォーマットのパラメーター ：

パラメーター名：テキスト

パラメーター値：

${Bug.ProjectOwner}さん、

次の課題が、${Bug.Severity}に設定されました。

${Issue.IssueKey} - ${Issue.IssueTitle}

期限：${Bug.DueDate}

カスタムパラメーター (名前 = 値) ：

user = <gateway_user_name>

password = <api_password>

api_id = <gateway_unique_api_id>

to = <user_mobile_number> 

上記のユーザー定義パラメーターとカスタムパラメーターは、デモ用にClickatell決済サービスを使用しています。   

手順3：業務ルールの設定

次の仕様で、ルールを作成します：

  1. 業務ルール名：致命的 
  2. 実行条件：項目の更新：重要度
  3. 条件：重要度が「致命的」、かつ、ステータスが「完了」ではない
  4. 処理：
    • 再現性：常に 
    • 担当者：開発者
    • Webhookの呼び出し：前の手順で作成したWebhookを選択します
  5. 業務ルールを保存します。業務ルールの作成についての 詳細はこちら をご参照ください。

手順4：Webhook連携のテスト

テスト用の課題をプロジェクトに追加して、開発者に割り当てます。また、［ 重要度 ］を「 致命的 」に変更します。これにより、上記のルールに関連付けられたWebhookが実行され、プロジェクト所有者が、 課題の件名 、 重要度 、 期限  が記載されたSMS通知を受信します。