マニュアルキャンセル

Webhook の設定

検索

最終更新日 : 2024年1月10日 | 次にも適用 : Adobe Acrobat Sign

Adobe Sign

アプリを開く

Adobe Acrobat Sign の統合
新機能
製品バージョンとライフサイクル
Salesforce 向け Acrobat Sign
Microsoft 向け Acrobat Sign
1. Microsoft 365 向け Acrobat Sign
  1. インストールガイド
2. Outlook 向け Acrobat Sign
  1. ユーザーガイド
3. Word/PowerPoint 向け Acrobat Sign
  1. ユーザーガイド
4. Teams 向け Acrobat Sign
5. Microsoft PowerApps および Power Automate 向け Acrobat Sign
  1. ユーザーガイド
  2. リリースノート
6. Acrobat Sign Connector for Microsoft Search
  1. ユーザーガイド
  2. リリースノート
7. Microsoft Dynamics 向け Acrobat Sign
8. Microsoft SharePoint 向け Acrobat Sign
ServiceNow 向け Acrobat Sign
HR ServiceNow 向け Acrobat Sign
1. インストールガイド（非推奨）
SAP SuccessFactors 向け Acrobat Sign
Acrobat Sign for Workday
NetSuite 向け Acrobat Sign
1. インストールガイド
2. リリースノート
SugarCRM 向け Acrobat Sign
VeevaVault 向け Acrobat Sign
Coupa BSM Suite 向け Acrobat Sign
1. インストールガイド
Zapier 向け Acrobat Sign
Acrobat Sign 開発者向けドキュメント

概要

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 web アプリケーション（以前の Adobe Sign）の webhook UI について説明します。

デベロッパー向けの API の詳細については、次の URL を参照してください。

REST v6 の詳細

使用方法

管理者は、まず 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 に配信され続けます。

前述のように、Sign からのすべての通知リクエストに含まれている「X-AdobeSign-ClientId」というヘッダーの値（クライアント ID）は、次の 2 つの方法のいずれかで、応答としてエコーバックされる必要があります。

1. HTTP ヘッダー X-AdobeSign-ClientId および、このクライアント ID としての値

クライアント ID を取得して検証し、応答ヘッダーに返す Javascript コードの例
// Fetch client id var clientid = request.headers['X-ADOBESIGN-CLIENTID']; //Validate it if (clientid ==="BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created { //Return it in response header response.headers['X-AdobeSign-ClientId'] = clientid; response.status = 200; // default value }

クライアント ID を取得して検証し、応答ヘッダーに返す PHP コードの例
<?php // Fetch client id $clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID']; //Validate it if($clientid == "BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created { //Return it in response header header("X-AdobeSign-ClientId:$clientid"); header("HTTP/1.1 200 OK"); // default value } ?>

2. キーが xAdobeSignClientId、クライアント ID が同じ値の JSON 応答の本文

クライアント ID を取得し、検証して応答の本文で返す Javascript コードの例
// Fetch client id var clientid = request.headers['X-ADOBESIGN-CLIENTID']; //Validate it if (clientid ==="BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created { var responseBody = { "xAdobeSignClientId" : clientid // Return Client Id in the body }; response.headers['Content-Type'] = 'application/json'; response.body = responseBody; response.status = 200; }

クライアント ID を取得し、検証して応答の本文で返す Javascript コードの例

// Fetch client id

var clientid = request.headers['X-ADOBESIGN-CLIENTID'];

//Validate it

if (clientid ==="BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created

{

var responseBody = {

"xAdobeSignClientId" : clientid // Return Client Id in the body

};

response.headers['Content-Type'] = 'application/json';

response.body = responseBody;

response.status = 200;

}

クライアント ID を取得し、検証して応答の本文で返す PHP コードの例
<?php // Fetch client id $clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID']; //Validate it if($clientid == "BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created { //Return it in response body header("Content-Type: application/json"); $body = array('xAdobeSignClientId' => $clientid); echo json_encode($body); header("HTTP/1.1 200 OK"); // default value } ?>

クライアント ID を取得し、検証して応答の本文で返す PHP コードの例

<?php

// Fetch client id

$clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID'];

//Validate it

if($clientid == "BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created

{

//Return it in response body

header("Content-Type: application/json");

$body = array('xAdobeSignClientId' => $clientid);

echo json_encode($body);

header("HTTP/1.1 200 OK"); // default value

}

応答の JSON 本文の例
{ "xAdobeSignClientId": "BGBQIIE7H253K6" }

前提条件

次のものが必要です。

Azure Functions アプリケーションを作成するためのライセンスのある Microsoft アカウント
既存の Azure Functions アプリケーションは、次の方法で作成可能 https://docs.microsoft.com/ja-jp/azure/azure-functions/functions-create-first-azure-function
選択した任意の言語でコードを理解して記述できる、Javascript の基本的な知識

Acrobat Sign webhook として機能する Azure Functions トリガーを作成する手順

Javascript HTTP トリガー関数を作成するには：

1. Microsoft アカウントでログインします：https://portal.azure.com/

2. 「Function App」タブに表示されている Azure Functions アプリケーションを開きます。

Azure Functions アプリケーションのリストが開きます。

3. この新しい関数を作成するアプリケーションを選択します。

4. 「作成」（+）ボタンをクリックして、新しい Azure 関数を作成します。

5. シナリオとして「Webhook + API」、言語として「Javascript」を選択します。

6. 「この関数を作成する」をクリックします。

受信 API リクエストを処理する機能を持つ新しい関数が作成されます。

Acrobat Sign webhook を登録するロジックの追加

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

以下の 2 つのオプションがあります。

オプション 1：X-AdobeSign-ClientId のクライアント ID を応答ヘッダーとして渡す

応答ヘッダーの X-AdobeSign-ClientId を渡します。これは、リクエストに渡されるヘッダーと同じヘッダーで、応答でエコーバックする必要があります。

Index.js ファイルを以下で置き換えます：

module.exports = function (context, req) {

var clientId = req.headers['x-adobesign-clientid'];

// Validate that the incoming ClientID is genuine

if (clientId === '123XXX456') {

context.res = {

// status: 200, /* Defaults to 200 */ // any 2XX response is acceptable

body: "Notification Accepted",

headers : {

'x-adobesign-clientid' : req.headers['x-adobesign-clientid']

}

};

}

else {

context.res = {

status: 400,

body: "Opps!! Illegitimate Call identified"

};

}

context.done();

};

リクエストをモックして、動作をテストします。

1. 右端にある「テスト」ボタンをクリックします。

2. ダミーのリクエストをモックします。

上記にはレスポンスヘッダーが表示されていませんが、postman／DHC や他のサービスでモックすることで確認できます。

オプション 2：xAdobeSignClientId キーを含む応答本文でクライアント ID を渡す

xAdobeSignClientId のキーとその値（リクエストヘッダーで送信されたクライアント ID と同じ値）を示す JSON 応答の本文内。

Index.js ファイルを以下で置き換えます：

module.exports = function (context, req) {

var clientId = req.headers['x-adobesign-clientid'];

// Validate that the incoming ClientID is genuine

if (clientId === '123XXX456') {

context.res = {

// status: 200, /* Defaults to 200 */ // any 2XX response is acceptable

body: {

'xAdobeSignClientId' : clientId

headers : {

'Content-Type' : 'application/json'

}

};

}

else {

context.res = {

status: 400,

body: "Opps!! Illegitimate Call identified"

};

}

context.done();

};

リクエストをモックして、動作をテストします。

1. 右端にある「テスト」ボタンをクリックします。

2. ダミーのリクエストをモックします。

また、webhook URL が POST 通知を受信するとき、clientID に対して同じ動作が期待されます。

使用準備完了

動作の検証が終了すると、webhook URL は Acrobat Sign 標準版に従って機能します。必要に応じて、カスタムロジックをさらに更新できます。

関数の URL の取得

「関数の URL の取得」をクリック

URL をコピーして、Acrobat Sign で webhook を作成するために使用します。

AWS Lambda 関数の作成

AWS Lambda 関数を作成するには、AWS Management Console にログインし、サービスリストから AWS Lambda サービスを選択します。

「『一から作成』を使用して Lambda 関数を作成」オプションをクリックします。
関数の設定ページで、関数名「lambdaWebhooks」を入力し、ランタイムとして「Node.js 4.3」を選択します。
「ロール」として、既存のロールを選択するか、テンプレートから新しいロールを作成します。
- 「テンプレートから新しいロールを作成」を選択した場合は、ロール名（role-lamda など）を入力し、「シンプルなマイクロサービスのアクセス許可 」をポリシーテンプレートリストから選択します。
「関数の作成」ボタンをクリックします。

新しい AWS lamda 関数ページで、「コードエントリタイプ」として「コードをインラインで編集」を選択し、ハンドラーは index.handler のままにします。
Acrobat Sign webhook を登録するロジックの追加
Acrobat Sign は、webhook の登録を完了する前に、登録リクエストで提供された webhook URL が、本当に通知を受信するかどうかを確認します。この目的のために、Acrobat Sign が新しい webhook 登録リクエストを受信すると、まず webhook URL に対して検証リクエストを作成します。この検証リクエストは、webhook URL に送信される HTTPS GET リクエストで、カスタム HTTP ヘッダー X-AdobeSign-ClientId を含みます。このヘッダーの値は、webhook の作成／登録を要求しているアプリケーションのクライアント ID に設定されます。Webhook を正常に登録するために、webhook URL はこの検証リクエストに 2XX 応答コードで応答する必要があり、さらに、次の 2 つの方法のいずれかで同じクライアント ID 値を返す必要があります。また、Webhook URL がイベント通知を受信する場合も、clientID に対して同じ動作がPOSTされます。

次のいずれかのケースに従います。

ケース 1：X-AdobeSign-ClientId のクライアント ID を応答ヘッダーとして渡す
- 応答ヘッダーの X-AdobeSign-ClientId を渡します。これは、リクエストに渡されるヘッダーと同じヘッダーで、応答でエコーバックする必要があります。
  
  コードスニペット
  index.js ファイルで、自動生成されたコードスニペットを次のコードで置き換えます。

クライアント ID を取得して検証し、応答ヘッダーに返すノード JS コードの例
exports.handler = function index(event, context, callback) { // Fetch client id var clientid = event.headers['X-AdobeSign-ClientId']; //Validate it if (clientid =="BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created { var response = { statusCode: 200, headers: { "X-AdobeSign-ClientId": clientid } }; callback(null,response); } else { callback("Oops!! illegitimate call"); } }

クライアント ID を取得して検証し、応答ヘッダーに返すノード JS コードの例

exports.handler = function index(event, context, callback) {

// Fetch client id

var clientid = event.headers['X-AdobeSign-ClientId'];

//Validate it

if (clientid =="BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created

{

var response = {

statusCode: 200,

headers: {

"X-AdobeSign-ClientId": clientid

}

};

callback(null,response);

}

else {

callback("Oops!! illegitimate call");

}

ケース 2：xAdobeSignClientId キーを含む応答本文でクライアント ID を渡す

xAdobeSignClientId のキーとその値（リクエストヘッダーで送信されたクライアント ID と同じ値）を示す JSON 応答の本文内。

コードスニペット

Index.js ファイルを以下で置き換えます。

クライアント ID を取得して検証し、応答ヘッダーに返すノード JS コードの例
exports.handler = function index(event, context, callback) { // Fetch client id var clientid = event.headers['X-AdobeSign-ClientId']; //Validate it if (clientid =="BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created { var responseBody = { xAdobeSignClientId : clientid }; var response = { statusCode: 200, body: JSON.stringify(responseBody) }; callback(null,response); } else { callback("Opps!! illegitimate call"); } }

クライアント ID を取得して検証し、応答ヘッダーに返すノード JS コードの例

exports.handler = function index(event, context, callback) {

// Fetch client id

var clientid = event.headers['X-AdobeSign-ClientId'];

//Validate it

if (clientid =="BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created

{

var responseBody = {

xAdobeSignClientId : clientid

};

var response = {

statusCode: 200,

body: JSON.stringify(responseBody)

};

callback(null,response);

}

else {

callback("Opps!! illegitimate call");

}

関数を保存します。Lambda 関数が作成され、リアルタイム webhook で使用する準備がほぼ整いました。

AWS API Gateway の設定

この Lambda 関数に HTTP メソッドからパブリックにアクセスできるようにするには、上記で作成した関数を API のバックエンドとして使用して、AWS API Gateway を設定する必要があります。

AWS Management Console で AWS サービスから「API Gateway」を選択し、「API の作成」ボタンをクリックします。

「新しい API の作成」ページで「新しい API」を選択し、API 名として「webhooks」と入力します。
「API の作成」ボタンをクリックします。
「アクション」ドロップダウンリストを選択し、「リソースの作成」オプションを選択します。
「プロキシリソースとして設定」オプションを選択し、リソース名として「validate」と入力し、リソースパスに {proxy+} と入力します。
「API Gateway CORS を有効にする」オプションをオフのままにし、「リソースの作成」ボタンをクリックします。
統合タイプとして「Lambda 関数プロキシ」を選択したままにし、「Lambda リージョン」ドロップダウンリストで Lambda 関数を作成したリージョン（おそらく API Gateway を作成するリージョンと同じ）を選択します。
Lambda 関数として「validate」と入力し、「保存」ボタンをクリックします。
「Lambda 関数に権限を追加」ポップアップウィンドウで、「OK」を選択します。

上記の手順の実行がすべて完了すると、次のような画面が表示されます。

API のデプロイ

次の手順は、この API をデプロイして使用できるようにすることです。

「アクション」ドロップダウンで「API をデプロイ」を選択します。
「デプロイメントステージ」で「新しいステージ」を選択し、「ステージ名」に「prod」（またはこのステージを識別する任意の名称）を入力します。
「デプロイ」ボタンをクリックします。

これで API を使用する準備ができました。次に示すように、青いボックスに呼び出し URL が表示されます。

リアルタイムの webhook URL として入力する必要があるので、この URL をメモしておきます。

使用準備完了

これで完了です。上記の URL を使用し、webhook URL として/webhooks API リクエストのPOSTに"/{nodeJSfunctionName}"を追加します。動作の検証が終了すると、webhook URL は
Acrobat Sign 標準版に従って機能します。必要に応じて、カスタムロジックをさらに更新または追加できます。

設定オプション

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

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

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

注意：

上記で説明した検証プロトコルに従って webhook 検証と webhook 通知のリクエストに応答するように、webhook URL を設定してください。Acrobat Sign web アプリケーションから作成された webhook に送信されるクライアント ID（アプリケーション ID）は、「UB7E5BXCXY」です。

スコープ

アカウント：アカウント内で発生するすべての購入済みイベントにより、プッシュがトリガーされます。
- アカウント管理者には、アカウントとそのアカウント内のすべてのグループに定義されているすべての 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 デベロッパーガイドを参照してください。

契約書：

UI 要素	Webhook 名
契約書のすべてのイベント	AGREEMENT_ALL
契約書が作成されました	AGREEMENT_CREATED
契約書が送信されました	AGREEMENT_ACTION_REQUESTED
契約書の参加者が完了しました	AGREEMENT_ACTION_COMPLETED
契約書ワークフローが完了しました	AGREEMENT_WORKFLOW_COMPLETED
契約書の期限が切れています	AGREEMENT_EXPIRED
契約書が削除されました	AGREEMENT_DOCUMENTS_DELETED
契約書がキャンセルされました	AGREEMENT_RECALLED
契約書が辞退されました	AGREEMENT_REJECTED
契約書が共有されました	AGREEMENT_SHARED
契約書が委任されました	AGREEMENT_ACTION_DELEGATED
契約書の参加者が置き換えられました	AGREEMENT_ACTION_REPLACED_SIGNER
契約書が変更されました	AGREEMENT_MODIFIED
契約書の変更が確認されました	AGREEMENT_USER_ACK_AGREEMENT_MODIFIED
契約書の電子メールが閲覧されました	AGREEMENT_EMAIL_VIEWED
契約書の電子メールが戻ってきました	AGREEMENT_EMAIL_BOUNCED
契約書の作成に失敗しました	AGREEMENT_AUTO_CANCELLED_CONVERSION_PROBLEM
オフラインイベント後に契約書が同期されました	AGREEMENT_OFFLINE_SYNC
送信者が契約書をアップロードしました	AGREEMENT_UPLOADED_BY_SENDER
契約書が格納されました	AGREEMENT_VAULTED
契約書の参加者のソーシャル ID が認証されました	AGREEMENT_WEB_IDENTITY_AUTHENTICATED
契約書の参加者の KBA が認証されました	AGREEMENT_KBA_AUTHENTICATED
契約書リマインダーが送信されました	AGREEMENT_REMINDER_SENT
署名者が変更した契約書の署名者名	AGREEMENT_SIGNER_NAME_CHANGED_BY_SIGNER

API 経由でのみ利用可能な契約書 webhook
NA	AGREEMENT_EXPIRATION_UPDATED
NA	AGREEMENT_READY_TO_NOTARIZE
NA	AGREEMENT_READY_TO_VAULT

一括送信：

UI 要素	webhook 名
一括送信の全イベント	MEGASIGN_ALL
一括送信を作成	MEGASIGN_CREATED
一括送信を共有	MEGASIGN_SHARED
一括送信をリコール	MEGASIGN_RECALLED

Web フォーム：

UI 要素	webhook 名
Web フォームのすべてのイベント	WIDGET_ALL
Web フォームが作成されました	WIDGET_CREATED
Web フォームは有効になりました	WIDGET_ENABLED
Web フォームは無効になりました	WIDGET_DISABLED
Web フォームが変更されました	WIDGET_MODIFIED
Web フォームが共有されました	WIDGET_SHARED
Web フォームの作成に失敗しました	WIDGET_AUTO_CANCELLED_CONVERSION_PROBLEM

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

UI 要素	webhook 名
NA	LIBRARY_DOCUMENT_ALL
NA	LIBRARY_DOCUMENT_CREATED
NA	LIBRARY_DOCUMENT_AUTO_CANCELLED_CONVERSION_PROBLEM
NA	LIBRARY_DOCUMENT_MODIFIED

通知パラメーター

通知パラメーターを使用すると、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 通知の送信時に、パートナーアプリケーションのアカウントから取得されたクライアント証明書（ある場合）を使用して、自身を識別します。

SSL/TSL 要件の詳細を確認する。

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

Web サーバー検証

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

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

いいえ。

Webhook コールバック URL は、ポート 443 または 8443 でのみ HTTPS にできます。

Acrobat Sign は、その他すべてのポートへのアウトバウンド HTTPS トラフィックをブロックします。

サーバー証明書を検証するには、DigiCert® SSL インストール診断ツールを使用することをお勧めします。

ホスト名のみを入力します（例：www.digicert.com）。

一般的な問題には、次のものがあります。

問題：信頼されていない CA または自己署名証明書の使用

修正：Webhook コールバックサーバーに、パブリック CA 発行の SSL 証明書を使用します。

問題：サーバーが中間証明書を送信しない

修正：Webhook コールバックサーバーに中間証明書をインストールします。

詳細については、https://www.digicert.com/jp/kb/ssl-certificate-installation.htm を参照してください。

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

Webhook に双方向 SSL を設定するには、管理者がプライベートキーを含む .p12（または .pfx）ファイルをアップロードする必要があります。ファイルはお客様のアカウント内に安全に保存され、管理者が随時削除できます。

双方向 Webhook の設定では、Acrobat Sign は呼び出し元／クライアントであり、お客様のアカウントに代わり Acrobat Sign が呼び出しを行ったことを証明するためにプライベートキーが必要です。

双方向 SSL が有効なことの確認

Webhook コールバックサーバーで双方向 SSL を有効にする必要があります。

任意の Web ブラウザーを使用して、Webhook コールバック URL に接続します。次のメッセージが表示されます。
```
400 Bad Request
No required SSL certificate sent
```
この場合、サーバーはクライアントがクライアント証明書を送信することを要求します（つまり、双方向 SSL がサーバーで有効になっています）。

上記のメッセージが表示されない場合、双方向 SSL は有効ではありません。

注意：

Postman を使用して、Webhook コールバック URL に POST リクエストを実行できます。同様の結果が出力されます。

ローカルでのクライアント証明書の確認

クライアント資格情報は、自己署名証明書または CA 発行証明書のいずれかになります。ただし、次の X.509 v3 拡張機能に最小限準拠する必要があります。

X.509 v3 拡張機能	Value
ExtendedKeyUsage	clientAuth（OID：1.3.6.1.5.5.7.3.2）
KeyUsage	digitalSignature

クライアント証明書は、拡張子が .p12 または .pfx の PKCS12 ファイルである必要があります。また、クライアント証明書（サーバーがクライアントの ID を検証できるようにする）とクライアントのプライベートキー（クライアントが SSL ハンドシェイク中にサーバーに対してメッセージをデジタル署名して検証できるようにする）の両方を含める必要があります。

次の openssl コマンドを使用して、p12（pfx）ファイルを検証します。

openssl pkcs12 -info -in outfile.p12

プライベートキーのパスフレーズが要求されます。出力には、次のように証明書と暗号化されたプライベートキーの両方が含まれています。

Bag Attributes
    localKeyID: 9D BD 22 80 E7 B2 B7 58 9E AE C8 42 71 F0 39 E1 E7 2B 57 DB
subject=/C=US/ST=California/L=San Jose/O=Adobe Inc./CN=sp.adobesignpreview.com
issuer=/C=US/O=DigiCert Inc/CN=DigiCert TLS RSA SHA256 2020 CA1
-----BEGIN CERTIFICATE-----
MIIGwDCCBaigAwIBAgIQAhJSKDdyQZjlbYO5MJAYOTANBgkqhkiG9w0BAQsFADBP
MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMSkwJwYDVQQDEyBE
...
JAKQLQ==
-----END CERTIFICATE-----
Bag Attributes: <No Attributes>
subject=/C=US/O=DigiCert Inc/CN=DigiCert TLS RSA SHA256 2020 CA1
issuer=/C=US/O=DigiCert Inc/OU=www.digicert.com/CN=DigiCert Global Root CA
-----BEGIN CERTIFICATE-----
MIIEvjCCA6agAwIBAgIQBtjZBNVYQ0b2ii+nVCJ+xDANBgkqhkiG9w0BAQsFADBh
MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3
...
-----END CERTIFICATE-----
Bag Attributes
    localKeyID: 9D BD 22 80 E7 B2 B7 58 9E AE C8 42 71 F0 39 E1 E7 2B 57 DB
Key Attributes: <No Attributes>
-----BEGIN ENCRYPTED PRIVATE KEY-----
MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQI7eNh2qlsLPkCAggA
...
FHE=
-----END ENCRYPTED PRIVATE KEY-----

証明書には、少なくともエンドエンティティ証明書と中間証明書が含まれている必要があります。ルート CA 証明書も含まれていることが理想的です。

警告 :

.p12 または .pfx ファイルがパスフレーズで保護されていることを確認します。

自己署名クライアント証明書の作成（オプション）

クライアント証明書は、必要に応じて CA 発行または自己署名のいずれかになります。

自己署名クライアント証明書を生成するには、次の openssl コマンドを使用します。

openssl req -newkey rsa:4096 -keyform PEM -keyout ca.key -x509 -days 3650 -outform PEM -out ca.cer

警告：

作成されたファイルは自己署名 CA 証明書であるため、公開しないようにします。
次に、クライアント .p12 ファイルを生成します。
1. SSL クライアントのプライベートキーを生成します。
  openssl genrsa -out client.key 2048
2. クライアントのプライベートキーを使用して証明書リクエストを生成します。
  openssl req -new -key client.key -out client.req
3. 証明書リクエストと CA 証明書／キーを使用して、クライアント証明書を発行します。
  openssl x509 -req -in client.req -CA ca.cer -CAkey ca.key -set_serial 101 -extensions client -days 365 -outform PEM -out client.cer
4. クライアント証明書とプライベートキーをブラウザーで使用できるように pkcs#12 形式に変換します。
  openssl pkcs12 -export -inkey client.key -in client.cer -out client.p12
5. pkcs12 に必要な情報がすべて含まれているため、クライアントのプライベートキー、クライアント証明書、クライアントリクエストファイルを削除します。
  rm client.key client.cer client.req
リモートサーバーに対するクライアント証明書の確認
- Postman を使用して、クライアント PFX ファイルを読み込みます（設定／証明書）。
- 「証明書の追加」を選択して、クライアント証明書を追加します。
- x-adobesign-clientid の HTTP ヘッダーを設定します。
設定が完了したら、Webhook コールバック URL に POST リクエストを送信します。

200 応答が表示されます。
Postman で PFX ファイルを確認した後でも、Acrobat Sign が PFX ファイルを拒否するのはなぜですか？

上記のプロセスに従って pfx ファイルを検証しても、Acrobat Sign が pfx ファイルを拒否する場合、非標準の PKCS12 ファイルを生成できる Microsoft ツールでファイルが生成された可能性があります。

この場合、次の openssl コマンドを使用して、証明書とプライベートキーを pfx ファイルから抽出し、適切な形式の PKCS12 ファイルを生成します。
```
// Extract certificates and private key from pfx file
openssl pkcs12 -info -in microsoftclientssl.pfx -passin pass:&quot;&quot; -out clientcert.crt -nokeys
openssl pkcs12 -info -in microsoftclientssl.pfx -passin pass:&quot;&quot; -out clientcert.key -nodes -nocerts

// Create new PKCS12 file
openssl pkcs12 -export -inkey clientcert.key -in clientcert.crt -out clientcert.pfx
```

有効／無効にする方法

Webhook 機能へのアクセスは、法人向けプランアカウントではデフォルトで有効になっています。

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

Webhook ページへのアクセスは、管理メニューの左パネルに表示されます：アカウント／Webhooks

Webhook をアクティベート

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

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

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

Webhook ヘッダー行の右側にあるオプションアイコン（3 本の横線）をクリックし、「すべての 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 に通知が送信されるように処理されます。つまり、webhook はすべての該当する契約書のイベントに対してトリガーされ、webhook が設定されているグループやアカウントの外部のものも含まれます。

通知は、参加者が関係するイベントに対してのみ配信されます。つまり、契約書の送信者は、ほとんどすべての通知を受け取るのに対し、契約書の受信者は、契約書への関与が開始されてから、関与しているイベントについてのみ通知を受け取ります。

Webhook 通知は、Acrobat Sign 自体の現在の認証および表示モデルに従います。つまり、ユーザーが契約書への参加を開始したときにのみ、契約書にアクセスできます。

送信者は、署名用の契約書を 3 人の署名者に送信します。

送信者アカウント用に設定されているアカウントレベルの WebhookX があります。
署名者 1 は、送信者と同じアカウントのメンバーであるが、別のグループに属しており、そのグループ用に設定されている WebhookY があります。
署名者 2 は、別のアカウントのメンバーであり、署名者 2 アカウント用に設定された、WebhookZ アカウントレベルがあります。
署名者 3 は、送信者と同じアカウントのメンバーです。

送信者が契約書を送信：「契約書作成済み」および「契約書送信済み」の場合に WebhookX がトリガーされ、「契約書送信済み」の場合に WebhookY がトリガーされます。

署名者 1 が署名：「契約書参加者の完了」および「契約書送信済み」で WebhookX がトリガーされ、「契約書参加者の完了」で WebhookY がトリガーされ、「契約書送信済み」で WebhookZ がトリガーされます。

署名者 2 が署名：「契約書参加者の完了」および「契約書送信済み」で WebhookX がトリガーされ、WebhookZ は「契約参加者の完了」通知を送信します。

署名者 3 が署名：「契約書参加者の完了」および「契約書ワークフローの完了」で WebhookX がトリガーされ、「契約書ワークフローの完了」で WebhookY がトリガーされ、「契約書ワークフローの完了」で WebhookZ がトリガーされます。

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

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

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

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

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

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

ヘルプをすばやく簡単に入手

新規ユーザーの場合

Adobe MAX Japan
クリエイターの祭典

2025 年 2 月 13 日
東京ビッグサイト

詳しく見る

Webhook の設定

概要

使用方法

Webhook URL のインテントの確認

Webhook 通知への応答方法

1. HTTP ヘッダー X-AdobeSign-ClientId および、このクライアント ID としての値

2. キーが xAdobeSignClientId、クライアント ID が同じ値の JSON 応答の本文

前提条件

Acrobat Sign webhook として機能する Azure Functions トリガーを作成する手順

Acrobat Sign webhook を登録するロジックの追加

オプション 1：X-AdobeSign-ClientId のクライアント ID を応答ヘッダーとして渡す

オプション 2：xAdobeSignClientId キーを含む応答本文でクライアント ID を渡す

使用準備完了

AWS Lambda 関数の作成

ケース 1：X-AdobeSign-ClientId のクライアント ID を応答ヘッダーとして渡す

ケース 2：xAdobeSignClientId キーを含む応答本文でクライアント ID を渡す

AWS API Gateway の設定

API のデプロイ

使用準備完了

設定オプション

スコープ

URL

イベント

契約書：

一括送信：

Web フォーム：

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

通知パラメーター

双方向 SSL 認証

Web サーバー検証

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

有効／無効にする方法

Webhook をアクティベート

Webhook のアクティベート解除

Webhook の表示または編集

Webhook の削除

ベストプラクティス

注意事項...

JSON のサイズ制限

Webhook 通知

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

ヘルプをすばやく簡単に入手