署名リクエストは非同期に実行されます。署名者はアプリ外も含め、いつでもリクエストを完了、拒否、または無視できます。保存先フォルダにWebhookを設定すると、それらのイベントが発生したときにアプリに通知されます。
Sign関連のイベント
フォルダまたはドキュメントにリスナーを設定します。通常は、署名リクエストを作成するフォルダに設定し、そのフォルダでのすべてのリクエストに1つのWebhookで対応できるようにします。
リッスンできるイベントの例:
SIGN_REQUEST.COMPLETED: 署名リクエストが完了した
SIGN_REQUEST.DECLINED: 署名リクエストが拒否された
SIGN_REQUEST.EXPIRED: 署名リクエストの有効期限が切れた
SIGN_REQUEST.SIGNER_EMAIL_BOUNCED: 署名者のメールが差し戻された
SIGN_REQUEST.SIGNER_SIGNED: 特定の署名者がリクエストに署名した
SIGN_REQUEST.SIGNATURE_REQUESTED: 署名が署名者にリクエストされた
SIGN_REQUEST.ERROR_FINALIZING: 署名リクエストを処理できなかった
トリガーの詳細な一覧は、Webhookトリガーを参照してください。
Sign Webhookの作成
Sign Webhookは、Boxの標準Webhookインフラストラクチャを使用しています。Box Signイベントを受信するためには、Webhookの作成エンドポイントを呼び出します。呼び出しでは、署名リクエストを作成するフォルダにtargetを設定したうえで、受信するSIGN_REQUEST.*トリガーを列挙する必要があります。
このAPIを使用するには、アプリケーションの [Webhookを管理する] スコープが有効になっている必要があります。
上記以外のWebhookの作成方法 (開発者コンソールを使った方法やSDKの例など) については、Webhookの作成 (v2) を参照してください。
Signイベント通知の受信
Box Signイベントが発生すると、BoxからHTTP POSTリクエストがユーザーの構成したaddressに送られます。このペイロードにはトリガーのほか、署名リクエストIDや署名者のメールアドレスなどのSign固有のadditional_infoが含まれます。また、署名リクエストのsourceファイルも含まれます。
たとえば、署名リクエストが完了すると、Boxから以下のようなペイロードが送られます。
エンドポイントは、200から299までのHTTPステータスコードに30秒以内に通知確認を送る必要があります。ペイロード全体の形式と配信の詳細については、Webhook (v2) を参照してください。通知がBoxから送信されたものかどうかを確認する方法については、Box Webhook署名の検証を参照してください。