ウェブフック
Webhookは、Zoho Workerlyでイベントが発生した際に即時Web通知を送信することで、サードパーティアプリケーションとの連携を可能にします。Webhookを使用することで、HTTP URLを設定し、ワークフロールールに関連付けて通知プロセス全体を自動化できます。
iDEAL ユーザー
- 管理ワークフロー権限を持つWorkerlyユーザー
- REST APIのスキルを持つプログラマー
権限必須: 管理ワークフロー権限を持つユーザーのみがこの機能にアクセスできます。
Webhookの項目一覧
| 項目名 | 説明 | データの種類 | 最大値 |
| 名前 | Webhookの名前を指定します。 | テキスト | 英数字(50) |
| 説明 | Webhookの説明を追加します。 | テキスト | 200文字以内 |
| URL to 通知 | サードパーティアプリケーションのREST API URLを指定してください。 | URL | 200文字以内 |
| Method | APIメソッドの種類（POSTまたは取得する）を選択してください。初期設定ではPOSTメソッドが選択されています。 | ラジオボタン | - |
| タブ |
Zoho Workerlyのタブのいずれかを選択してください。 対応タブ：
メモ：通話ログおよびメモタブにはWebhookを設定できません。 |
ピッキングリスト | - |
| Append 項目 パラメーター |
Parameter 名前と対応するParameter 値を指定します。Webhook通知をサードパーティアプリケーションに送信する際、これらがリクエストパラメーターとして送信されます。 対応タブ：
|
String | 3000文字 |
| Append カスタム パラメーター | Webhook用のWorkerly Parameter 名前と対応する値を指定します。Webhookをトリガーする際にも、これらがリクエストパラメーターとして送信されます。名前と値は設定された内容となります。このキー／値ペアは主に認証トークンやセキュリティトークンなどを送信する際に使用されます。 | String | - |
| プレビューする URL | 通知先となるサードパーティアプリケーションの完了Webhook URLをプレビューします。 | テキスト | 閲覧のみ |
Webhookの設定
Webhookの設定は、以下の3つのステップで行います：
- Webhook を作成します。
- Webhook をワークフロー ルールに関連付けます。
- Webhook の連携をテストします。
Webhook を作成するには
- 設定 > 自動化 > ワークフロー > Webhook に移動します。
- Webhook ページで、「Webhook を設定」をクリックします。
- 新規 Webhook ページで、必要なすべてのパラメーターを指定します。
- 「保存」をクリックします。
サポートされていないマージ項目値の認識
Webhook の値説明エディターで使用しているマージ項目値が、${Unsupported_Field} と表示されることがあります。これには以下のような理由があります。
カスタム項目が削除された場合
挿入したマージ項目の値が削除されています。Webhook の値説明エディターに削除済みの項目のマージ項目値が残っている場合、その値は ${Unsupported_Field} と表示されます。
カスタム look-up 項目が削除された場合
挿入したカスタム look-up 項目の値が削除されています。Webhook の値説明エディターに削除済み look-up 項目のマージ項目値が残っている場合、その値は ${Unsupported_Field} と表示されます。
利用可能なマージ項目一覧に表示されていない項目
選択したタブの利用可能なマージ項目一覧に含まれていない項目のマージ項目値を使用すると、${Unsupported_Field} と表示されます。例えば、Job Openings タブの値説明エディターで ${Candidates。Candidate Id} を挿入した場合は、サポートされていない項目として表示されます。
Webhook をワークフロー ルールに関連付けるには：
- 設定 > 自動化 > ワークフローに移動します。
- ワークフロー ルールページで、「ルール作成」をクリックします。
- 「新しいルールを作成する」ページで、ワークフルールのパラメーターを指定します。
- ワークフロー処理で「Webhook」を選択します。
- 「通話Webhook」ポップアップで、必要なWebhookを選択し、「関連付ける」をクリックします。
- 「保存」をクリックします。
Webhook連携をテストするには：
- ワークフルールの条件に従い、Workerlyにテストデータを追加します。
- アプリケーション側で、Webhook通知を通じてZoho Workerlyから受信したデータを確認します。
- エラーやデータ不一致があれば、Zoho Workerly内のWebhook設定を修正してください。
- Zoho Workerlyからアプリケーションへ必要なデータが取得できるまで、このテストを繰り返します。
メモ
- 1つのワークフロールールにつき、最大6つ（インスタント操作1件と時間ベース処理5件）のWebhookを関連付けできます。
- Webhookを使用して、Zoho Workerlyからサードパーティアプリケーションへ最大10件のWorkerly項目データを転送できます。
- Webhookを利用して、他のアプリケーションからZoho Workerlyへデータを取得することはできません。
- APIチケットは、サードパーティアプリケーションの制限に従い、定期的に更新する必要があります。
- サードパーティAPIの問題でWebhook連携が停止した場合、メール通知は届きません。
- Webhook（POSTメソッド使用時）では、ユーザー定義形式の最大10,000文字まで許可されています。
- 処理に失敗した場合、Webhookが最初に通知を送信し、15分後にZoho Workerlyシステムが2回目の通知を送信します。それ以降は、そのワークフロートリガーに対するWebhook通知は送信されません。
- 1日の最大件数を超えた場合、それ以降のWebhook通知はサードパーティアプリケーションへ送信されず、失敗が管理者に通知されます。
- 通知項目用URLでポート番号を指定する場合、80または443のみサポートされていますのでご注意ください。
- Webhookパラメータ設定時に、必須の日付/日時形式やタイムゾーンを選択できます。
- Webhookの上限：
- プロフェッショナルエディション：10,000通話/日 または 100通話/ユーザーライセンス（いずれか少ない方）
- エンタープライズエディション：20,000通話/日 または 500通話/ユーザーライセンス（いずれか少ない方）
法人シナリオ
多数の採用が行われるため、すべての派遣スタッフにSMSで注意喚起を送信する必要があります。Webhookを利用することで、このプロセスが簡素化されます。
目的
大量採用イベントについて、SMSで派遣スタッフへ通知します。
前提条件
- SMS決済サービスのアカウント
- ワークフローRuleへのアクセス権限
手順
- SMS決済サービスでアカウントを作成
- Zoho WorkerlyでWebhookを設定
- ワークフローRuleを設定
- Webhook連携をテスト
手順 1: SMS決済サービスでアカウントを作成
SMS決済サービスでアカウントを作成し、Webhook設定のために以下の情報を取得してください。
- Workerlyer
- Candidate名前
- Opportunity金額
- Interview詳細
- Interview予定時間
現在、Zohoは以下のSMS決済サービスプロバイダーと提携しています。
- Twilio
- Clickatell
- Screen Magic
- メッセージMedia
上記の仕入先からSMSクレジットやAPI情報を購入できます。
手順 2: Zoho WorkerlyでWebhookを設定
ユーザー定義パラメーターを設定する際、Interviewsタブから以下の項目を選択してください。
- SMS決済サービスのドメイン名
- ユーザー名
- 認証トークン
Webhookでは、以下の詳細を指定してください。
通知先URL：
- http://<ドメイン名>/smsgateway/post - POSTメソッド
- ユーザー定義パラメーター（XMLまたはJSON）
- <ユーザー名>xxxx@xxxxx。com
- SMS-Provider
- XXXXXXX
- XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
- <メッセージ mobilenumber='${ユーザー.モバイル}'>こんにちは ${Interviews。Interviewer}様、${Interviews.差出人}より${Interviews.場所}で候補者：${Interviews。Candidate 名前}の面接が予定されています。
メモ
上記のXML文字列では、デモンストレーション目的でScreen Magic決済サービスを使用しています。
手順 3: ワークフロールールの設定
ワークフロールールのページで以下の手順に従ってください。
-
すべての新規インタビューに対してワークフローを作成します。
- 種類は新規法人です。
- ステージは完了済みWonです。
- Closing日付を選択します。
- 上記の手順に従いWebhookを設定します。
- 保存をクリックし、関連付けを行います。
- ワークフロールールを保存します。
手順 4: Webhook連携のテスト
- テスト用インタビューデータを追加し、すべての更新済みインタビュー詳細を入力します。
- ご自身の携帯電話番号でSMS通知を確認します。SMSが受信できなかった場合は、Webhookの設定を修正し、引き続きテストしてください。テストが成功した後、テスト用エントリを削除し、この連携をWorkerlyユーザーへ展開します。
エラーコード参照
Webhookの実行に失敗した場合、Zoho Workerlyでは以下のいずれかのエラーメッセージが表示されます。
HTTPステータスコード
- 400 Bad Request - 必須パラメーターが不足している場合があります。
- 401 Unauthorized - 有効な認証トークンが提供されていません。
- 402 リクエスト失敗 - パラメーターは有効ですが、リクエストが失敗しました。
- 404 Not Found - リクエストされた商品が存在しません。
- 500, 502, 503, 504 Server errors - サードパーティアプリケーション側でエラーが発生しました。
- エラーコード 1 - 一時的にAPIサーバーへ接続できません。APIサーバーログおよびファイアウォール設定を確認し、Workerlyから送信されたリクエストが許可されているかご確認ください。
カスタムエラー
- 内部処理エラー - Webhook が次の値と等しくない場合に、Webhook の処理中にエラーが発生した際に実行されます。
- 日次上限到達 - 会社がその日の最大 limit に達した場合に発生します。