Webhookの設定

Webhookの設定

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

Webhookは、開発者が2つのアプリケーションを連携させるためによく使用するコールバックの仕組みです。イベントや操作が発生するたびに、連携先のアプリケーションに更新情報を通知します。

Zoho SignのWebhook

Zoho Signでは、Webhookを設定して、Zoho Signで発生するイベントの更新情報を受け取ることができます。Webhookの作成時に、実行のきっかけとなるイベントを選択します。イベントは、文書イベントと受信者イベントに分類されます。

文書イベント

イベント
説明
送信済み
署名または承認を求める文書が送信されると実行されます。
全員が完了
すべての受信者による文書への署名と承認が完了すると実行されます。
期限切れ
署名または承認を求めて送信された文書の期限が切れると実行されます。
取り消し済み
署名または承認を求めて送信された文書を送信者が取り消すと実行されます。

受信者イベント

イベント
説明
表示済み
いずれかの受信者が文書を表示すると実行されます。
受信者による署名完了
いずれかの受信者が文書に署名すると実行されます。
受信者による承認完了
いずれかの受信者が文書を承認すると実行されます。
拒否済み
いずれかの受信者が文書を拒否すると実行されます。
再割り当て済み
いずれかの受信者が、文書の署名または承認を別の人に再割り当てすると実行されます。
ハードバウンス
署名要求メールまたは署名者の認証メールでハードバウンスが発生すると実行されます。

前提条件

  1. Webhookは現在、エンタープライズ、API、Zoho One、People Plusの各プランで利用できます。
  2. 1つのアカウントにつき、最大2件のWebhookを作成できます。

Webhookの登録方法

  1. Zoho Signの管理者は、左側のナビゲーションパネルで[設定]→[開発者向け設定]→[Webhook]の順にクリックして、Webhookを登録できます。
  2. [Webhookの作成]をクリックします。
  3. コールバックURLとWebhookの名前を入力します([URLのテスト]をクリックして、URLにアクセスできることを確認します)。
  4. 実行条件を設定すると、選択したすべてのイベントではなく、指定した条件に一致するイベントに対してのみWebhookを実行できます。設定した条件に一致しないイベントでは、コールバックは実行されない点にご注意ください。条件を設定しない場合は、[コールバックイベント]で選択したすべてのイベントに対してコールバックが実行されます。
  5. 実行条件を設定するには:
    1. [コールバックの実行条件]で、確認する項目を選択します。
    2. 条件を選択します。
    3. [値を入力]に、照合する値を入力します。
    4. 別の条件を追加するには、+アイコンをクリックします。
  6. [コールバックイベント]で、Webhookの実行のきっかけとなる文書イベントと受信者イベントを選択します。
  7. セキュリティ設定を行い、[保存]をクリックします。



Webhookのセキュリティ保護

セキュリティ設定では、エンドポイントに送信される要求を認証し、各ペイロードの完全性を検証できます。セキュリティの設定方法についてはこちらをご覧ください。

認証

  1. 基本認証 - ユーザー名とパスワードでエンドポイントを保護します。認証情報はBase64でエンコードされ、すべての要求のAuthorizationヘッダーで送信されます。
  2. OAuth 2.0 - Zoho Signは、クライアント認証情報による認可方式を使用してトークンURLからアクセストークンを取得し、すべての要求でBearerトークンとして送信します(OAuth 2.0と基本認証を同時に有効にすることはできません)。
  3. 相互TLS認証 - クライアント証明書を使用してエンドポイントを認証します。PEM形式の証明書と秘密鍵、またはPFX/P12形式のバンドルをアップロードします(一度に有効にできる形式は1つのみです)。
  4. カスタム要求ヘッダー - 追加の認証やルーティングのために、すべての要求にカスタムHTTPヘッダーを付加します。ヘッダー名は最大5件まで追加できます。

完全性

  1. HMAC署名 - HMAC SHA-256署名の検証を有効にして、受信したペイロードを認証し、完全性を確認します。秘密鍵を入力または生成すると、Zoho Signは各ペイロードに署名し、その結果をX-ZS-WEBHOOK-SIGNATUREヘッダーで送信します。設定後、保存された秘密鍵をZoho Signから取得することはできません。アプリケーションでWebhookのペイロードを検証する際に必要となるため、安全に保管してください。
  2. タイムスタンプ - 各要求にタイムスタンプ(X-ZS-WEBHOOK-TIMESTAMPヘッダー)を含め、リプレイ攻撃の防止に役立てます。



Webhookのペイロード

  1. 各Webhookイベントで、次のペイロードが送信されます。
  2. このペイロードは、「notifications」と「requests」という2つのキーを持つJSONオブジェクトで、各キーにはJSONオブジェクトが格納されます。
  3. notificationsオブジェクトには文書に対して行われた操作の詳細が、requestsオブジェクトにはWebhookが呼び出された対象文書の詳細が含まれます。

構造

  1. {
  2. 'notifications':
  3. {
  4. 'performed_by_email': '<email address of the person performing the operation. ',
  5. 'performed_by_name': '<user who performed this operation',
  6. 'performed_at': <time value in java current time in mills format>,
  7. 'reason': '操作の理由(指定されている場合)',
  8. 'activity': '<small description of activity performed',
  9. 'operation_type': 'RequestSubmitted | RequestViewed | RequestSigningSuccess | RequestCompleted | RequestRejected | RequestRecalled | RequestForwarded | RequestExpired',
  10. 'action_id': '<sign action id',
  11. 'ip_address': '<ip address captured during this operation>'
  12. },
  13. 'requests':
  14. {
  15. 'request_status': '<status of the document>',
  16. 'request_name': '<name of the sign request>',
  17. 'request_id': '<long value - primary key of the signature request',
  18. 'document_ids':
  19. [
  20. {
  21. 'document_name': '<name of the document inside signature request',
  22. 'document_id': '<long value - of the document contained inside request'
  23. }
  24. ]
  25. }
  26. }
ペイロードの例:
  1. {
  2. 'notifications':
  3. {
  4. 'performed_by_email': 'testuser@zoho.com',
  5. 'performed_at': 1555062604837,
  6. 'reason': '指定された理由(ある場合)',
  7. 'activity': '文書に署名しました',
  8. 'operation_type': 'RequestSigningSuccess',
  9. 'action_id': '1000000000090',
  10. 'performed_by_name': 'テストユーザー',
  11. 'ip_address': '192.168.100.100'
  12. },
  13. 'requests':
  14. {
  15. 'request_name': '秘密保持契約書',
  16. 'request_id': '1000000000000',
  17. 'org_id': '9876543210',
  18. 'request_type_id': '10000000011',
  19. 'document_ids':
  20. [
  21. {
  22. 'document_name': 'CommonNDA.pdf',
  23. 'document_id': '100000000000050'
  24. }
  25. ]
  26. }
  27. }
メモ:
  1. 通知のJSONオブジェクト内のoperation_type属性には、アクションの実行条件となる、次の定義済み定数のいずれかが入ります。この属性は、発生したイベントの種類を識別するうえで重要な役割を果たします。
操作の種類
実行条件
RequestSubmitted
文書が署名のために送信されたとき。
RequestViewed
送信済みの文書が閲覧されたとき。
RequestSigningSuccess
署名者のいずれかが署名手続きを正常に完了したとき。
RequestCompleted
指定されたすべての署名者または承認者が、署名または承認の手続きを完了したとき。
RequestRejected
送信済みの署名要求が拒否されたとき。
RequestRecalled
送信者が送信済みの署名要求を取り消したとき。
RequestForwarded
指定された署名者が、送信済みの要求を別の人に転送したとき。
RequestExpired
送信済みの文書の署名期限が過ぎたとき。

  1. RequestViewed、RequestSigningSuccess、RequestRejected、RequestForwardedなど、署名者に関連するアクションの場合、'notifications'のJSON内に署名者の'action_id'が含まれます。
  2. 通知ペイロードに含まれるその他のデータは、標準のデータ属性ではなく、今後予告なく削除される可能性があります。ドキュメントに記載されている属性のみを使用することをお勧めします。