Zoho PeopleのWebhook

Zoho PeopleのWebhook

Webhookとは

この機能を使用すると、特定の処理が実行されたときの、外部アプリへのリアルタイムのデータ転送や通知を自動化できます。ユーザーがZoho Peopleで処理を実行するたびに、指定したURLに通知が送信されることで、遅延なく最新の情報を把握できます。また、 外部アプリと効率的に連携が可能です。

Webhookはユーザー定義の「HTTPコールバック」とも呼ばれ、HTTP POST経由で送信される自動イベント通知として機能します。あらかじめ設定した処理が実行されるたびに、指定されたURLにメッセージを配信して通知します。

Webhookの設定

  1. サービス内のフォームに対して独自のWebhookを作成して、新規または既存のワークフローに関連付けます。
  2. ワークフローで特定の操作が行なわれると、Webhookが実行され、Zoho Peopleから外部アプリに自動通知が送信されます。

Webhookのメリット

  1. 柔軟にカスタマイズできる
  2. 外部アプリに即時通知を送信できる
  3. 独自アプリや外部アプリと連携できる
  4. リアルタイムにデータを同期できる
  5. 処理結果を確認できる

Webhookの種類

  1. Webhookの一覧：ユーザーがZoho Peopleアカウントで操作を行うたびに、外部アプリに対して通知を送信できます。
  2. 失敗したWebhook：Webhook名、フォーム名、関連データ、最新の呼び出し時間、処理の再実行、処理結果のメッセージといった詳細とともに、このページに一覧表示されます。また、フォーム名、Webhook名、期間などを指定して、データを抽出することも可能です。
  3. 成功したWebhook：Webhook名、フォーム名、関連データ、最新の呼び出し時間、処理の再実行、処理結果のメッセージといった詳細とともに、このページに一覧表示されます。また、フォーム名、Webhook名、期間などを指定して、データを抽出することも可能です。

APIとは

Zoho Peopleでは、外部アプリケーションと連携を行うにあたってAPIを利用できます。APIを利用すると、従業員やフォームのデータをXMLまたはJSON形式のファイルで抽出することが可能です。このファイルをもとに、新しいアプリケーションを開発したり、外部アプリケーションと連携したりすることができます。Zoho PeopleのAPIでは、あらゆるプログラミング言語（Java、.Net、C、C++、PHP）でアプリケーションを開発できます。

詳細については、こちらをクリックしてください。

Webhookの項目

項目名 説明 データの種類 上限
Webhook名 Webhookの名前 テキスト 英数字（50文字）
説明 Webhookの説明 テキスト 250文字
通知先のURL 外部アプリまたはZohoのアプリのAPIとURLを指定します（例：Zoho People、Zoho Creator）。 URL 250文字
メソッド APIメソッドの種類（POSTまたはGET）を選択します。標準ではPOSTが選択されています。 ラジオボタン ー
モジュール 外部アプリにデータを送信する「フォーム」を選択します。 選択リスト ー
フォームの項目の追加 ［パラメーターの名前］と対応する［パラメーターの値］に入力します。これは、外部アプリにWebhookを実行する間に送信されるリクエストのパラメーターです。 文字列 3,000文字
独自のパラメーターの追加 Webhook用のパラメーター名と対応する値を指定します。これは、Webhookを実行する際に送信されるリクエストのパラメーターでもあります。名前と値は設定どおりです。このキーと値のペアは、主に認証トークンやセキュリティトークンを送信するために使用されます。 文字列 ー
URLのプレビュー 外部アプリに通知されるWebhook URL全体をプレビューします。 テキスト 表示のみ
 

Webhookの設定

Webhookの機能はシンプルで、容易に設定できます。HTTP URLを設定し、ワークフロールールに関連付けるだけで、ワークフローの処理を自動化できます。任意のサービスにWebhookを設定するには、以下の手順に従ってください。

  1. ［設定］→任意のサービス→［自動化］→［操作］→［Webhook］の順に移動します。
  2. ［Webhookを追加する］をクリックします。
  3. Webhookの設定ページでは、以下の手順に従って設定します。
  4. 変更イベント発生時にWebhookを実行するサービス内のフォームを選択します。
  5. ［Webhook名］を入力します。
  6. ［通知先のURL］を指定します。
  7. ［説明］（Webhookの使用目的）を入力します。
  8. APIメソッドを［POST］または［GET］から選択します。
  9. 必要なクエリーパラメーターの指定
    Info
    ［パラメーターの名前］と対応する［パラメーターの値］を指定します。ユーザー定義の形式でパラメーターを指定すると、最大10件のエンティティ項目をパラメーターとして追加できます。例：XML、JSONなど、独自のパラメーター名とパラメーター値を指定します。独自のパラメーターは、最大5件まで追加できます。

  10. 必要に応じて、カスタムHTTPヘッダーを追加します。カスタムHTTPヘッダーを追加することにより、リクエストヘッダー内で認証トークン、セキュリティトークン、APIキー、その他の認証情報を安全に送信できます。
  11. URLのプレビューを確認します。URLの更新ボタンをクリックすると、URLを更新できます。
  12. ［保存する］をクリックします。
    Webhookが保存され、ワークフローにタグ付けできるようになります。

Webhookとワークフローの関連付け

Webhookを実行する条件を持つワークフローを作成して、Webhookをワークフローに関連付けます。

Webhookをワークフローに関連付けるには
  1. ［設定］→任意のサービス→［自動化］→［ワークフロー］→［ワークフローを追加する］の順に移動します。
  2. 入力が必要な項目すべてに入力します。
  3. ［操作］で［Webhook］欄にある［+］（追加）アイコンをクリックして、ワークフローに新しいWebhookを追加するか、フォームに作成された既存のWebhookを選択します。
  4. ［追加する］をクリックします。
    ワークフローが追加されます。特定の操作が行われると、Webhookが実行され、外部アプリに通知が送信されます。

利用例

Webhookによる退職フォームの従業員ステータス変更

ある従業員が退職することになり、従業員フォームのステータスを「退職」に変更する場合の手順です。Webhook導入前は、従業員フォームと退職フォームの両方で変更を手動で更新する必要がありました。しかし、APIを使用してWebhookを設定すると、従業員フォームでの変更が退職フォームに通知され、自動で更新できるようになります。この利用例でWebhookを設定するには、以下の手順に従ってください。

  1. ［設定］→任意のサービス→［自動化］→［操作］→［Webhook］の順に移動します。
  2. ［Webhookを追加する］をクリックします。
  3. Webhookの設定ページでは、以下の手順に従って設定します。
  4. ［フォーム名］のドロップダウンを使用して、従業員フォームを選択します。
  5. ［Webhook名］を入力します。
  6. ［通知先のURL］を以下のように入力します。
  7. ［説明］を入力します。
  8. APIメソッドの種類は［POST］を選択します。
  9. URLクエリーパラメーターを以下のように入力します。
    Quote
    ユーザー定義のフォーマットの場合：パラメータ名「xmlData」と値「Description」を以下のように指定します。
    <Request>
    <Record>
    <field name='Employee_ID'>${ZOHO_LINK_ID}</field>
    <field name='Interviewer'>${Reporting_To}</field>
    <field name='Separation_date'>${Exit_Date}</field>
    </Record>
    </Request>
    Info
    上記のXML文字列では、tag fieldはZoho Peopleの項目、nameは項目のラベル名、valueタグは送信されるデータを表しています。
  10. 独自のパラメーターを入力します。authtokenをパラメータ名、authtokenキーをパラメータ値に指定します。
    Info
    APIを使用するには、Zoho Peopleアカウントの認証トークンが必要です。Zoho PeopleのAPIガイドについては、こちらをクリックしてください。
  11. ［保存する］をクリックします。
Info
このWebhookをワークフローに関連付けて、実行条件とする処理を定義します。