本ブログシリーズは、「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(); \\ エンベロープイベント（完了）を追加する（受信者イベントを追加することも可能） 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 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