DocuSign eSignature APIでできること - エンベロープにDocuSign Connect Webhookを追加する

本ブログシリーズは、「DocuSign eSignature APIでできること」と題しまして、シンプルながらも有用なAPIタスクについてご紹介するシリーズです。第1回目の記事では、DocuSign eSignature APIを使用して、通知メールの件名とメッセージ本文をカスタマイズする方法をご紹介しました。そして、前回の記事では、エンベロープのデータを取得する方法について解説しました。シリーズ3回目となる今回は、DocuSignのWebhookテクノロジー「DocuSign Connect」を使用した、カスタムWebhookの設定方法についてご説明します。

DocuSign Connectとは

DocuSignにAPIリクエストを送信し、情報を取得したり、特定のアクションをDocuSignに指示したりするインテグレーションを構築する場合、コードで呼び出しを行い、DocuSignが受信したリクエストに応答します。これは「ポーリング」と呼ばれます。これとは反対に、DocuSignがアプリケーションへリクエストを送信し、システム内で発生したイベントを通知する方法もあります。これは「Webhook」と呼ばれ、これを行うには、システム内でオブジェクトが更新された際に、DocuSignが呼び出しを行う専用のURLを設定します。

DocuSign Connectの設定方法

DocuSign Connectを設定する方法は2つあります。どちらの方法でも、DocuSign eSignature APIの呼び出しが必要となります（ウェブツールから行うことはできません）。1つ目は、DocuSign Connect Webhookをアカウント全体に設定する方法です。これにより、DocuSignアカウントの管理者ユーザーが、DocuSign Connect設定を作成することができます。DocuSign Connect設定は、アカウント上のすべてのユーザーとエンベロープに適用される点に注意してください。今回ご紹介するのは、2つ目の方法で、DocuSign Connectを使用して、エンベロープが所定のWebhookを呼び出すようリクエストする方法です。エンベロープは、DocuSign eSignature APIを通して作成する必要があり、呼び出しにはエンベロープにDocuSign Connectを追加するために必要な情報を含みます。この方法だと、アカウント上のすべてのエンベロープのイベントを処理する必要がなく、Connect設定の上限（100）に達することもありません。

コード例

以下のコードには、エンベロープに受信者と文書を追加する部分が含まれていませんが、コードの他の部分に追加されていると仮定してください。カスタムDocuSign Connect Webhookをエンベロープに追加する方法は次のとおりです。

C#

EnvelopeDefinition envelopeDefinition = new EnvelopeDefinition();
var eventNotification = new EventNotification();
\\ エンドポイントURLを設定する（HTTPSプロトコルで、TLS1.1以降のバージョン）
eventNotification.Url = "https://myapp.somedomain.com";
\\ 受信の確認ができない場合、配信を再試行するように設定する
eventNotification.RequireAcknowledgment = "true";
\\ 文書をイベントとともにエンドポイントに送信する
eventNotification.IncludeDocuments = "true";
\\ DocuSign管理者画面でConnectログが確認できるようにする
eventNotification.LoggingEnabled = "true";
var envelopeEvents = new List<EnvelopeEvent>();
\\ エンベロープイベント（完了）を追加する（受信者イベントを追加することも可能）
envelopeEvents.Add(new EnvelopeEvent { EnvelopeEventStatusCode = "completed", IncludeDocuments = "true" });
eventNotification.EnvelopeEvents = envelopeEvents;
envelopeDefinition.EventNotification = eventNotification;

Java

EnvelopeDefinition envelopeDefinition = new EnvelopeDefinition();
EventNotification eventNotification = new EventNotification();
\\ エンドポイントURLを設定する（HTTPSプロトコルで、TLS1.1以降のバージョン）
eventNotification.setUrl("https://myapp.somedomain.com");
\\ 受信の確認ができない場合、配信を再試行するように設定する
eventNotification.setRequireAcknowledgment("true");
\\ 文書をイベントとともにエンドポイントに送信する
eventNotification.setIncludeDocuments("true");
\\ DocuSign管理者画面でConnectログが確認できるようにする
eventNotification.setLoggingEnabled("true");
java.util.List<EnvelopeEvent> envelopeEvents = new java.util.arrayList();
\\ エンベロープイベント（完了）を追加する（受信者イベントを追加することも可能）
EnvelopeEvent envelopeEvent = new EnvelopeEvent();
envelopeEvent.setEnvelopeEventStatusCode("completed");
envelopeEvent.setIncludeDocuments("true");
envelopeEvents.add(envelopeEvent);
eventNotification.setEnvelopeEvents(envelopeEvents);
envelopeDefinition.setEventNotification(eventNotification);

Node.js

let envelopeDefinition = new docusign.EnvelopeDefinition();
let eventNotification = new docusign.EventNotification();
\\ エンドポイントURLを設定する（HTTPSプロトコルで、TLS1.1以降のバージョン）
eventNotification.url = 'https://myapp.somedomain.com';
\\ 受信の確認ができない場合、配信を再試行するように設定する
eventNotification.requireAcknowledgment = 'true';
\\ 文書をイベントとともにエンドポイントに送信する
eventNotification.includeDocuments = 'true';
\\ DocuSign管理者画面でConnectログが確認できるようにする
eventNotification.loggingEnabled = 'true';
let envelopeEvents = [];
\\ エンベロープイベント（完了）を追加する（受信者イベントを追加することも可能）
let envelopeEvent = new docusign.EnvelopeEvent();
envelopeEvent.envelopeEventStatusCode = 'completed';
envelopeEvent.includeDocuments = 'true';
envelopeEvents.push(envelopeEvent);
eventNotification.envelopeEvents = envelopeEvents;
envelopeDefinition.eventNotification = eventNotification;

PHP

$envelopeDefinition = new \DocuSign\eSign\Model\EnvelopeDefinition();
$eventNotification = new \DocuSign\eSign\Model\EventNotification();
# エンドポイントURLを設定する（HTTPSプロトコルで、TLS1.1以降のバージョン）
$eventNotification->setUrl('https://myapp.somedomain.com');
# 受信の確認ができない場合、配信を再試行するように設定する
$eventNotification->setRequireAcknowledgment('true');
# 文書をイベントとともにエンドポイントに送信する
$eventNotification->setIncludeDocuments('true');
# DocuSign管理者画面でConnectログが確認できるようにする
$eventNotification->setLoggingEnabled('true');
$envelopeEvents = [];
# エンベロープイベント（完了）を追加する（受信者イベントを追加することも可能）
$envelopeEvent = new \DocuSign\eSign\Model\EnvelopeEvent();
$envelopeEvent->setEnvelopeEventStatusCode('completed'),
$envelopeEvent->setIncludeDocuments('true');
array_push($envelopeEvents, $envelopeEvent);
$eventNotification->setEnvelopeEvents($envelopeEvents);
$envelopeDefinition->setEventNotification($eventNotification);

Python

envelope_definition = EnvelopeDefinition()
event_notification = EventNotification()
# エンドポイントURLを設定する（HTTPSプロトコルで、TLS1.1以降のバージョン）
event_notification.url = 'https://myapp.somedomain.com'
# 受信の確認ができない場合、配信を再試行するように設定する
event_notification.require_acknowledgment = 'true'
# 文書をイベントとともにエンドポイントに送信する
event_notification.include_documents = 'true'
# DocuSign管理者画面でConnectログが確認できるようにする
event_notification.logging_enabled = 'true'
envelope_events = []
# エンベロープイベント（完了）を追加する（受信者イベントを追加することも可能）
envelope_event = EnvelopeEvent()
envelope_event.envelope_event_status_code = 'completed'
envelope_event.include_documents = 'true'
envelope_events.append(envelope_event)
event_notification.envelope_events = envelope_events
envelope_definition.event_notification = event_notification

Ruby

envelope_definition = DocuSign_eSign::EnvelopeDefinition.new
event_notification = EventNotification.new
# エンドポイントURLを設定する（HTTPSプロトコルで、TLS1.1以降のバージョン）
event_notification.url = 'https://myapp.somedomain.com'
# 受信の確認ができない場合、配信を再試行するように設定する
event_notification.require_acknowledgment = 'true'
# 文書をイベントとともにエンドポイントに送信する
event_notification.include_documents = 'true'
# DocuSign管理者画面でConnectログが確認できるようにする
event_notification.logging_enabled = 'true'
envelope_events = []
# エンベロープイベント（完了）を追加する（受信者イベントを追加することも可能）
envelope_event = DocuSign_eSign::EnvelopeEvent.new
envelope_event.envelope_event_status_code = 'completed'
envelope_event.include_documents = 'true'
envelope_events.push(envelope_event)
event_notification.envelope_events = envelope_events
envelope_definition.event_notification = event_notification

カスタムDocuSign Connect Webhookを、アプリケーションで作成したエンベロープに追加する方法については以上です。次回は、エンベロープにリマインダーと有効期限を設定する方法をご紹介します。どうぞお楽しみに。

Original post: Common API Tasks – Add a Connect Webhook to your Envelopes