Webhook の設定

概要

Webhook は、ソースサイト（この場合は Adobe Acrobat Sign）で購入済みイベントが発生したときにトリガーされる、ユーザー定義の HTTPS リクエストです。

事実上、webhook はデータまたはデータストリームを受け入れる REST サービスです。

Webhook は、プッシュモデルでのサービス間通信を目的としています。

購入済みイベントがトリガーされると、Acrobat Sign は JSON 本文を持つ HTTPS POST を構築し、指定された URL に配信します。

Webhook には、以前のコールバックメソッドに比べて次のような多くの利点があります。

• 管理者は、コールバック URL を一覧するために Acrobat Sign サポートを必要とすることなく、webhook を有効にできる
• Webhook は、データの「鮮度」、通信の効率、セキュリティの点で優れていてポーリングは不要
• Webhook では、さまざまなレベルのスコープ（アカウント／グループ／ユーザー／リソース）を簡単に使用できる
• Webhook はより先進的な API ソリューションであり、先進的なアプリケーションをより簡単に設定できる
• コールバックを一意にする必要がある場合、スコープ（アカウント／グループ／ユーザー／リソース）ごとに複数の webhook を構成できる
• Webhook では、返されるデータを選択できるが、その場合コールバックは「全部か無」ソリューションである
• Webhook で伝送するメタデータは構成できる（基本または詳細）
• Webhook では、管理者が UI を完全に制御できるため、必要に応じてはるかに簡単に作成、編集したり、無効にできる

使用方法

管理者は、まず、Acrobat Sign からのインバウンドプッシュを受け入れる準備が整った webhook サービスを用意する必要があります。これに関しては多くのオプションがありますが、サービスが POST と GET のリクエストを受け入れ可能な限り、webhook は成功します。

サービスを導入したら、Acrobat Sign 管理者は、Acrobat Sign サイトの webhook インターフェイスから新しい webhook を作成できます。

管理者は、契約書、web フォーム（ウィジェット）または一括送信（MegaSign）イベントをトリガーするように Webhook を設定できます。ライブラリテンプレート（ライブラリ文書）リソースは、API から設定することもできます。

Webhook のスコープには、管理インターフェイスをからアカウント全体または個々のグループを含めることができます。API を使用すると、USER または RESOURCE スコープを選択して、より詳細に設定できます。

URL にプッシュされるデータのタイプは設定可能で、契約書情報、参加者情報、文書情報などを含めることができます。

Webhook を設定して保存すると、Acrobat Sign は、購入済みイベントがトリガーされるたびに、定義された URL に新しい JSON オブジェクトをプッシュします。イベントトリガー条件や JSON ペイロードを変更する場合を除き、webhook の継続的な操作は必要ありません。

Webhook URL のインテントの確認

Acrobat Sign は、webhook の登録を完了する前に、登録リクエストで提供された webhook URL が通知を受信するかどうかを確認します。このため、Acrobat Sign は、新しい webhook 登録リクエストを受信すると、まず webhook URL に対する検証リクエストを実行します。 この確認要求は、Webhook URL に送信される HTTPSGET要求です。 このリクエストには、カスタム HTTP ヘッダー X-AdobeSign-ClientId が含まれます。このヘッダーの値は、webhook の作成／登録を要求している API アプリケーションのクライアント ID（アプリケーション ID）に設定されます。Webhook を正常に登録するために、webhook URL はこの検証リクエストに 2XX 応答コードで応答する必要があり、さらに、次の 2 つの方法のいずれかで同じクライアント ID 値を返す必要があります。

• 応答ヘッダー X-AdobeSign-ClientId を使用。これは、リクエストで渡されたヘッダーと同じヘッダーで、応答でエコーバックされます。
• または、xAdobeSignClientId のキーとその値（リクエストで送信されたクライアント ID と同じ値）を示す JSON 応答の本文を使用。

応答（2XX 応答コード）に成功し、かつヘッダーまたは応答本文のいずれかでクライアント ID を検証した場合にのみ、webhook は正常に登録されます。この検証リクエストの目的は、webhook URL がその URL で通知を受信することを望んでいることを示すことです。間違った URL を入力してしまうと、URL は意図した検証リクエストに正しく応答しないため、Acrobat Sign はその URL に通知を送信しません。さらに、webhook URL は、特定のアプリケーションによって登録された webhook からのみ通知を受信することも検証できます。これは、X-AdobeSign-ClientId ヘッダーに渡されたアプリケーションのクライアント ID を検証することで実行できます。Webhook URL がそのクライアント ID を認識しない場合は、成功応答コードで応答せず、Acrobat Sign は、その URL が webhook として登録されていないものとして扱います。

Webhook URL 呼び出しの検証は、次のシナリオで行われます。

• Webhook の登録：この Webhook URL 呼び出しの検証が失敗すると、Webhook は作成されない
• Webhook の更新：非アクティブからアクティブへ：この Webhook URL 呼び出しの検証が失敗した場合、Webhook の状態は「アクティブ」に変更されない

Webhook 通知への応答方法

Acrobat Sign は、Webhook URL に送信される各 Webhook 通知リクエストで、インテントの暗黙的な検証を実行します。したがって、すべての webhook 通知 HTTPS リクエストには、X-AdobeSign-ClientId と呼ばれるカスタム HTTP ヘッダーも含まれています。このヘッダーの値は、webhook を作成したアプリケーションのクライアント ID（アプリケーション ID）です。Webhook 通知が正常に配信されたと見なされるのは、次の場合のみです。成功応答（2XX 応答コード）が返され、クライアント ID が HTTP ヘッダー（X-AdobeSign-ClientId）または JSON 応答本文で、キーが xAdobeSignClientId、値が同じクライアント ID として送られた場合です。それ以外の場合は、再試行の回数が終了するまで、通知が webhook URL に配信され続けます。

設定オプション

Webhook を設定するには、次の 5 つの要素を定義する必要があります。

• 名前：他の管理者が簡単に理解できる直観的な名前が推奨されます。
• スコープ：webhook がキャッチするネットの範囲アカウントとグループはインターフェイスで使用できます。
  • API は、アカウント、グループ、ユーザー、リソースのスコープをサポートします。
  • Webhook ごとに 1 つのスコープのみを定義できます。
• URL：Acrobat Sign が JSON ペイロードをプッシュしたターゲット URL。
• イベント：Acrobat Sign による JSON の構築と URL へのプッシュを引き起こすトリガー。
  • 各イベントは、トリガーイベントに関連する異なるペイロードを構築します。
  • 1 つの webhook に複数のイベントを含めることができます。
• 通知パラメーター：通知パラメーターは、イベントの JSON ペイロードのセクションを特定するので、この webhook にとって重要なイベントのセクションのみを選択できます（これにより、URL に送信される不要なデータが削減されます）。

Webhook を完全に定義して、「保存」をクリックすると、新しい webhook がトリガーイベントに即座に反応し始めます。

スコープ

• アカウント：アカウント内で発生するすべての購入済みイベントにより、プッシュがトリガーされます。
  
  • アカウント管理者には、アカウントとそのアカウント内のすべてのグループに定義されているすべての webhook を表示する権限があります。
• グループ：グループ内で発生するすべての購入済みイベントにより、プッシュがトリガーされます。注意：グループをスコープとする webhook は、その 1 つのグループにのみ存在します。
  • グループ管理者には、自分のグループ専用の webhook のみが表示されます。アカウントレベルの webhook や他のグループにバインドされている webhook は表示されません。
  • 「ユーザーの複数グループ所属」が有効になっているアカウントでは、スコープを適用するグループを設定するオプションが表示されます。
    
• ユーザーアカウント：ユーザーアカウントのすべての購入済みイベントによりプッシュがトリガーされます。ユーザーレベルの webhook は、API からのみ作成できます。
• リソースレベルの webhook：これは、特定のリソース用に作成されます。このリソースに固有のイベントが、webhook URL にプッシュされます。リソースレベルの webhook は、API からのみ作成できます。

URL

Webhook URL は、イベントの発生時にトリガーされる受信 HTTPS POST 通知メッセージをリッスンするサーバーです。

イベントへの webhook をサブスクライブするには、この URL が必要です。

• クライアントには、Acrobat Sign が POST できる HTTPS URL を含める必要があります。この URL は、パブリックインターネット上で利用できる必要があります。  
  • 例えば、127.0.0.1 やローカルホスト URL は機能しません。
  • URL エンドポイントは、ポート 443 または 8443（コールバック URL の定義時にお客様が決定）でリッスンする必要があります。
• Webhook が受信イベント通知の POST リクエストと検証リクエストの GET リクエストをサポートしていることを確認してください。
• URL はファイアウォールでブロックしないでください。

イベント

以下は、webhook URL へのプッシュをトリガーできるイベントです。オブジェクト別にグループ化され、UI に表示される順序で示されています。

左側の値は、Acrobat Sign UI に表示される値です。右側の値は、API での webhook 名です。

Webhook とそのペイロードについて詳しくは、Acrobat Sign デベロッパーガイドを参照してください。

契約書：

一括送信：

Web フォーム：

ライブラリテンプレート（API のみ）：

通知パラメーター

通知パラメーターを使用すると、JSON ペイロードをイベントの特定の要素のみにカスタマイズできます。

例えば、契約書参加者の置換イベントで、契約情報および参加者情報のみが必要な場合、文書情報を除外することで、webhook URL に送信される JSON の合計サイズを小さくすることができます。

• 契約書
  • 契約書情報：イベントトリガー時の契約書のステータスに基づく詳細な契約書情報。
  • 契約文書情報：イベントの結果として生成された文書情報を含みます。
  • 契約書参加者情報：イベントの結果として参加者情報を含みます。
  • 契約署名済み文書：署名済み PDF を提供します。
    • 契約書ワークフローの完了およびすべての契約書イベントに適用できます。
• 一括送信
  
  • 一括送信情報：イベントをトリガーした一括送信オブジェクトに関する詳細情報。
• Web フォーム
  • ウィジェット情報：イベントをトリガーした web フォームに関する詳細情報。
  • ウィジェットの文書情報：web フォームに関連付けられている文書情報。
    
  • ウィジェットの参加者情報：web フォームに定義された参加者に関する情報。

双方向 SSL 認証

双方向 SSL は、クライアント側 SSL または相互 TLS とも呼ばれ、サーバーとクライアント（Web ブラウザー）の両方が自身を識別するための証明書を提示する SSL モードです。

アカウント管理者は、セキュリティ設定ページでクライアント側の証明書を構成できます。

Acrobat Sign は、webhook URL にペイロードを配信する際に SSL 証明書を検証します。SSL 証明書の検証に失敗した webhook は、JSON ペイロードを正常に配信しません。 

双方向 SSL を使用してクライアント（Acrobat Sign）とリッスンサービスを認証し、Acrobat Sign のみが webhook URL に到達できるようにします。 

Webhook がパートナーアプリケーションにより作成された場合は、webhook は、webhook 通知の送信時に、パートナーアプリケーションのアカウントから取得されたクライアント証明書（ある場合）を使用して、自身を識別します。

以下に、web サーバー検証プロセスとクライアント証明書の検証の両方に関する一般的な質問を示します。

Web サーバー検証

Webhook の登録時に、Acrobat Sign は Webhook サーバーの URL を検証します。

Acrobat Sign から Webhook コールバック URL への接続が完了できない場合、お客様は Webhook を登録できません。

クライアント証明書の検証

有効／無効にする方法

Webhook 機能へのアクセスは、エンタープライズ版レベルのアカウントではデフォルトで有効になっています。

グループレベルの管理者は、自分のグループ内でのみ動作する webhook を作成／制御できます。

Webhook ページへのアクセスは、管理メニューの左パネルに表示されます。

Webhook をアクティベート

Webhook が最初に作成されるとき、「アクティブ」ステータスで作成されます。

Acrobat Sign の webhook ページには、デフォルトでアクティブな webhook が表示されます。

非アクティブな webhook をアクティブにするには：

• Webhook ヘッダー行の右側にあるオプションアイコン をクリックし、「すべての Webhook を表示」を選択します

• 非アクティブな webhook をシングルクリック
  • これにより、ヘッダー行のすぐ下に webhook のオプションが表示されます
• 「アクティベート」をクリックします

アクティブな webhook は、次のイベントがトリガーされるとすぐに、ターゲット URL へのデータ送信を開始します。

Webhook のアクティベート解除

Webhook をディアクティベートするには、次の操作を行うだけです。

• Webhook ページに移動
• アクティベート解除する webhook をシングルクリック
• ヘッダー行の下のメニュー項目から「アクティベート解除」を選択
  • アクティベート解除されると、webhook には「非アクティブ」ステータスが表示されます

Webhook の表示または編集

Webhook はいつでも編集して保存でき、新しい設定を保存すると、その変更はすぐに有効になります。

ただし、編集できるのは、イベントおよび通知パラメーターのみです。

名前、スコープまたは URL を変更する必要がある場合は、新しい webhook を作成する必要があります。

Webhook のパラメーターを編集するには：

• Webhook ページに移動
• 編集する webhook をシングルクリック
• ヘッダー行の下の「表示／編集」オプションをクリック

• 必要な変更を適用し、「保存」をクリック

Webhook の削除

Webhook はいつでも削除できます。

Webhook を削除するとシステム内で破棄されるため、削除された webhook を復元することはできません。

Webhook を最初にアクティベート解除する必要はありません。

Webhook を削除するには：

• Webhooks に移動
• 削除する webhook をシングルクリック
• ヘッダー行の下の「削除」オプションをクリック
• Webhook を削除するかどうかを確認するメッセージが表示されるので、「OK」をクリック

ベストプラクティス

• 特定の必要なイベントをサブスクライブして、サーバーに対する HTTPS リクエストの数を制限する：webhook をより具体的なものにするほど、取捨選択する量を少なくできます。
• 重複耐性がある：同じ webhook URL を共有する複数のアプリケーションがあり、各アプリケーションに同じユーザーがマッピングされている場合、同じイベントが webhook に複数回送信されます（アプリケーションごとに 1 回ずつ）。場合によっては、webhook が重複するイベントを受信することがあります。Webhook アプリケーションはこれを許容し、イベント ID によって重複排除を行う必要があります。
• 常に Webhook にすばやく応答する：アプリケーションが webhook リクエストに応答できる時間は 5 秒だけです。検証リクエストでは、これはほとんど問題になりません。なぜならアプリケーションは応答するために実際の作業を実行する必要がないためです。しかし、通知リクエストの場合、アプリがリクエストへ応答するのに時間がかかる作業が発生することがよくあります。5 秒以内に応答できるように、別のスレッドで作業するか、キューを使用して非同期で作業することをお勧めします。
• 並行処理の管理：ユーザーが次々に連続して変更を行うと、ほぼ同時に同じユーザーに対する複数の通知がアプリケーションに送信される可能性があります。並行処理の管理方法に注意しないと、同じユーザーに対して同じ変更が複数回処理されてしまうおそれがあります。Acrobat Sign webhook を活用するには、情報の使用方法を明確に理解する必要があります。次のような問いかけをしてください。
  • ペイロードにはどのようなデータを返すか
  • この情報にアクセスするのは誰か
  • どのような意思決定や報告が行われるか
• 署名済み文書を受信するための推奨事項：文書管理システムで Acrobat Sign から署名済み PDF を受け取る方法を決定する際には、いくつかの要因を考慮する必要があります。

単に「契約署名済み文書」オプションを選択しても差し支えありませんが、webhook を作成する際に、イベント（契約書の完了ステータスなど）のトリガーを受信したときに、Acrobat Sign API を使用して文書を取得することを検討することもできます。

注意事項...

JSON のサイズ制限

JSON ペイロードのサイズは 10 MB に制限されています。

イベントがこれより大きなペイロードを生成する場合、webhook はトリガーされますが、条件パラメーター属性（リクエスト内にある場合）は、ペイロードのサイズを減じるために削除されます。

これが発生したときは、応答で "ConditionalParametersTrimmed" が返され、クライアントに conditionalParameters 情報が削除されたことを伝えます。

“conditionalParametersTrimmed“ は array オブジェクトで、トリミングされたキーに関する情報を含みます。

切り捨ては以下の順序で行われます。

• includeSignedDocuments
• includeParticipantsInfo
• includeDocumentsInfo
• includeDetailedInfo

署名済み文書は、最初に切り捨てられ、続いて、参加者情報、文書情報、最終的に詳細情報が切り捨てられます。

これは、例えば、契約書完了イベントに署名済み文書（base 64 でエンコード）が含まれている場合や、複数のフォームフィールドを持つ契約書などで発生します。

Webhook 通知

Acrobat Sign webhook は、通知を契約書の送信者および契約書の送信元のグループ内で設定されているすべての webhook に配信します。アカウントスコープの webhook は、すべてのイベントを受信します。

リッスンサービスがダウンしているときの再試行

Webhook のターゲット URL が何らかの理由でダウンしている場合、Acrobat Sign は JSON をキューに入れ、72 時間にわたるプログレッシブサイクルでプッシュを再試行します。

未配信のイベントは再試行キューに保持され、発生順に通知を配信するために、次の 72 時間にわたってベストエフォート型配信が実行されます。

通知配信の再試行戦略では、試行間隔を倍増し、1 分間隔から始めて 12 時間ごとまでに増やします。結果として、72 時間の間に 15 回の再試行が行われます。

Webhook 受信者が 72 時間以内に応答せず、過去 7 日間に通知の配信が成功しなかった場合、webhook は無効になります。Webhook が再度有効になるまで、この URL に通知は送信されません。

Webhook が無効になってから再度有効になるまでの通知はすべて失われます。