Acrobat Sign Webhook の概要

概要

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

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

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

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

Webhook を設定する前に、ネットワークが機能に必要な IP 範囲を受け入れることを確認してください。

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

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

前提条件

サービスを機能させるには、ネットワークセキュリティを介して webhook の IP 範囲を許可する必要があります。

REST v5 の従来のコールバック URL サービスは、webhook サービスと同じ IP 範囲を使用します。

使用方法

管理者は、まず 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 機能へのアクセスは、エンタープライズ版レベルのアカウントではデフォルトで有効になっています。

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

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

同時実行ベースのレート制限

Webhook（およびコールバック）の作成および通知イベントは、Acrobat Sign システムからお客様に配信される同時通知の数に制限されます。この制限はアカウントに適用され、アカウント内のすべてのグループが含まれます。
このタイプのレート制限により、不適切にデザインされた 1 つのアカウントが過度の量のサーバーリソースを消費し、そのサーバー環境内の他のすべてのお客様に悪影響を与えることを防ぎます。

アカウントごとの同時イベント数が計算され、適切に動作する webhook を持つアカウントが最短時間で通知を受信するようにします。また、要求が多すぎるために通知が遅延する状況が発生することはほとんどありません。現在のしきい値は次のとおりです。

ベストプラクティス

• 特定の必要なイベントをサブスクライブして、サーバーに対する 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 が無効になってから再度有効になるまでの通知はすべて失われます。