Webhookの設定と活用方法

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

Webhook は、2 つのアプリケーションを連携させるために開発者がよく利用するコールバック方式です。連携されたアプリケーションでイベントや操作が発生するたびに、リアルタイムで更新情報を提供します。定期的なポーリングが必要となる API ベースのモデルと比べて優れた仕組みです。Webhook は、より効率的で広く利用されている連携方法です。

Zoho Sign Webhook

Zoho Sign では、Zoho Sign 内で発生する処理について、Webhook を設定してリアルタイムの更新情報を取得できます。

イベント送信対象	説明
送信済み	ドキュメントが署名用に送信されたときにトリガーされます。
Viewed	ドキュメントが受信者のいずれかによって閲覧されたときにトリガーされます。
Signed by a recipient	ドキュメントが受信者のいずれかによって署名または承認されたときにトリガーされます。
すべて完了	ドキュメントがすべての受信者によって完全に署名および承認されたときにトリガーされます。
却下済み	ドキュメントが受信者のいずれかによって却下されたときにトリガーされます。
Reassigned	ドキュメントが、受信者の 1 人によって別のユーザーに再割り当てされ、そのユーザーが署名または承認するように変更されたときにトリガーされます。
Expires	ドキュメントが署名用に送信され、その承認期限が切れたときにトリガーされます。
Recalled	ドキュメントが署名または承認用に送信された後、送信者によってリコールされたときにトリガーされます。
承認済み	ドキュメントが受信者のいずれかによって承認されたときにトリガーされます。

前提条件:

現在、Webhook は Enterprise、API、Zoho One、People Plus プランでのみ利用できます。
現在、1 アカウントあたり 2 件までの Webhook を作成できます。

Webhook を登録する方法:

Zoho Sign の管理者は、設定 > Developer 設定 > 左側の操作画面にある Webhook をクリックして、Webhook を登録できます。
Webhook を作成 をクリックし、コールバック URL や名前などの必要な情報を入力します。また、この Webhook を実行する対象の処理の一覧も表示されます。
Webhook を保護したい場合は、HMAC 署名のチェックボックスを有効にし、自分で作成したシークレットキーを入力します。まだシークレットキーがない場合は、［生成する］ボタンをクリックします。

一度設定すると、保存されたシークレットキーは Zoho Sign から取得できません。

Webhook のペイロードをアプリケーション側で認証する際にシークレットキーが必要になるため、シークレットキーは安全に保管してください。
該当する設定を選択し、Webhook の登録を完了します。

Zoho Sign における Webhook セキュリティの仕組みについては、こちらをクリックして参照してください。

Webhook ペイロード:

各 Webhook イベントについて、以下のペイロードが送信されます。
このペイロードは、内部に JSON オブジェクトを持つ '通知' と 'requests' の 2 つのキーからなる JSON オブジェクトです。
通知オブジェクトにはドキュメントに対して実行された操作の詳細が含まれ、requests オブジェクトには Webhook が呼び出された対象ドキュメントの詳細が含まれます。

構造:

{
'通知':
{
'performed_by_email': '<操作を実行したユーザーのメールアドレス>',
'performed_by_name': '<この操作を実行したユーザー名>',
'performed_at': <現在時刻を表す Java のミリ秒形式の時間値>,
'理由': '<必要に応じて、この操作に対して入力された理由>',
'活動': '<実行された活動の簡単な説明>',
'operation_type': 'RequestSubmitted | RequestViewed | RequestSigningSuccess | RequestCompleted | RequestRejected | RequestRecalled | RequestForwarded | RequestExpired',
'action_id': '<署名操作 ID>',
'ip_address': '<この操作時に取得された IP アドレス>'
},
'requests':
{
'request_status': '<ドキュメントのステータス>',
'request_name': '<署名リクエストの名前>',
'request_id': '<署名リクエストの主キーとなる long 値>',
'document_ids':
[
{
'document_name': '<署名リクエスト内のドキュメント名>',
'document_id': '<リクエスト内に含まれるドキュメントの long 値>'
}
]
}
}

サンプルペイロード:

{
'通知':
{
'performed_by_email': 'testuser@zoho.com',
'performed_at': 1555062604837,
'理由': '必要に応じて指定される理由',
'活動': 'ドキュメントに署名されました',
'operation_type': 'RequestSigningSuccess',
'action_id': '1000000000090',
'performed_by_name': 'テストユーザー',
'ip_address': '192。168。100。100'
},
'requests':
{
'request_name': 'NDA ドキュメント',
'request_id': '1000000000000',
'org_id': '9876543210',
'request_type_id': '10000000011',
'document_ids':
[
{
'document_name': 'CommonNDA。pdf',
'document_id': '100000000000050'
}
]
}
}

メモ:

通知 JSON オブジェクト内の operation_type 属性には、処理が実行されたときに使用される、あらかじめ定義された定数のいずれかが入ります。この属性は、発生したイベントの種類を特定するうえで重要な役割を果たします。

オペレーションタイプ	トリガーされる理由
RequestSubmitted	ドキュメントが署名用に送信されたとき。
RequestViewed	送信済みドキュメントが閲覧されたとき。
RequestSigningSuccess	署名者のいずれかが署名プロセスを正常に完了したとき。
RequestCompleted	割り当てられたすべての署名者または承認者が、署名または承認プロセスを完了したとき。
RequestRejected	送信済みの署名依頼が却下されたとき。
RequestRecalled	送信済みの署名依頼が送信者によって取り消されたとき。
RequestForwarded	送信済みの依頼が、割り当てられた署名者によって別のユーザーに転送されたとき。
RequestExpired	送信済みドキュメントが、割り当てられた署名期限を過ぎたとき。

RequestViewed、RequestSigningSuccess、RequestRejected、RequestForwarded などの署名者に関連する処理では、「通知」JSON 内に署名者の 'action_id' が含まれます。
通知データの一部として送信されるその他のすべてのデータは標準データ属性ではなく、今後いつでも削除される可能性があります。ユーザーは、ドキュメントで説明されている属性のみを使用することを推奨します。