Common API Tasks🐈: Add a Connect Webhook to your Envelopes
Greetings, everyone! If you are reading this and wondering, what are "common API asks," I encourage you to take a look at the first two posts in the series. In the first post, I showed you how to set a custom email message for your envelope recipients, and in the second, I explained how to get the tab information from your envelopes. In this third post in the series I’m going to show you how to set a custom webhook using DocuSign's webhook technology, DocuSign Connect.
What is DocuSign Connect?
As developers, you write integrations that typically make API requests to DocuSign and either retrieve information or tell DocuSign to perform a certain action. In this model, your code initiates the call and DocuSign responds to your request upon receiving it: this method is called polling. There’s another model where DocuSign initiates a request to your app to indicate some event occured in the system. In that model, the developer sets up a dedicated URL that DocuSign calls into when objects were updated in the system: this method is called a webhook. For example, DocuSign Connect will let you know when there has been a change of status for an envelope in your account.
Two ways to set up DocuSign Connect
DocuSign Connect can be set in two different ways. Both ways require developers to make DocuSign eSignature API calls (there's no way to do that from the web tool). The first way is to set a global DocuSign Connect webhook for the account. That means a DocuSign account user with administrative privileges can create a Connect Configuration. The Connect Configuration would apply for all users and envelopes in the account. This blog post is focused on the second approach, which allows a developer to request that a specific envelope be set to call the specified webhook using DocuSign Connect. The envelope must be created via the DocuSign eSignature API and the call, as I’m going to show you here, would include the information needed to register DocuSign Connect for this envelope. This approach has the advantage of being flexible, since you don’t have to process events for all the envelopes in the account. It also skirts the maximum number of Connect Configurations, which is limited to 100.
Code please!
Happy to oblige. For the snippets below, I assume you have other parts of the code that add recipients and documents to the envelope. Here is how to add a custom DocuSign Connect webhook notification for your envelope in our six SDK languages:
C#
EnvelopeDefinition envelopeDefinition = new EnvelopeDefinition();
var eventNotification = new EventNotification();
// Set up the endpoint URL to call (it must be using HTTPS and at least TLS1.1 or higher)
eventNotification.Url = "https:\\myapp.somedomain.com";
// DocuSign will retry on failure if this is set
eventNotification.RequireAcknowledgment = "true";
// This would send the documents together with the event to the endpoint
eventNotification.IncludeDocuments = "true";
// Allows you to see this in the DocuSign Admin Connect logs section
eventNotification.LoggingEnabled = "true";
var envelopeEvents = new List<EnvelopeEvent>();
// In this case we only add a single envelope event, when the envelope is completed. You can also add events for recipients
envelopeEvents.Add(new EnvelopeEvent { EnvelopeEventStatusCode = "completed", IncludeDocuments = "true" });
eventNotification.EnvelopeEvents = envelopeEvents;
envelopeDefinition.EventNotification = eventNotification;
Java
EnvelopeDefinition envelopeDefinition = new EnvelopeDefinition();
EventNotification eventNotification = new EventNotification();
// Set up the endpoint URL to call (it must be using HTTPS and at least TLS1.1 or higher)
eventNotification.setUrl("https:\\myapp.somedomain.com");
// DocuSign will retry on failure if this is set
eventNotification.setRequireAcknowledgment("true");
// This would send the documents together with the event to the endpoint
eventNotification.setIncludeDocuments("true");
// Allows you to see this in the DocuSign Admin Connect logs section
eventNotification.setLoggingEnabled("true");
java.util.List<EnvelopeEvent> envelopeEvents = new java.util.arrayList<EnvelopeEvent>();
// In this case we only add a single envelope event, when the envelope is completed. You can also add events for recipients
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();
// Set up the endpoint URL to call (it must be using HTTPS and at least TLS1.1 or higher)
eventNotification.url = 'https:\\myapp.somedomain.com';
// DocuSign will retry on failure if this is set
eventNotification.requireAcknowledgment = 'true';
// This would send the documents together with the event to the endpoint
eventNotification.includeDocuments = 'true';
// Allow you to see this in the DocuSign Admin Connect logs section
eventNotification.loggingEnabled = 'true';
let envelopeEvents = [];
// In this case we only add a single envelope event, when the envelope is completed. You can also add events for recipients
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();
# Set up the endpoint URL to call (it must be using HTTPS and at least TLS1.1 or higher)
$eventNotification->setUrl('https:\\myapp.somedomain.com');
# DocuSign will retry on failure if this is set
$eventNotification->setRequireAcknowledgment('true');
# This would send the documents together with the event to the endpoint
$eventNotification->setIncludeDocuments('true');
# Allows you to see this in the DocuSign Admin Connect logs section
$eventNotification->setLoggingEnabled('true');
$envelopeEvents = [];
# In this case we only add a single envelope event, when the envelope is completed. You can also add events for recipients
$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()
# Set up the endpoint URL to call (it must be using HTTPS and at least TLS1.1 or higher)
event_notification.url = 'https:\\myapp.somedomain.com'
# DocuSign will retry on failure if this is set
event_notification.require_acknowledgment = 'true'
# This would send the documents together with the event to the endpoint
event_notification.include_documents = 'true'
# Allows you to see this in the DocuSign Admin Connect logs section
event_notification.logging_enabled = 'true'
envelope_events = []
# In this case we only add a single envelope event, when the envelope is completed. You can also add events for recipients
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
# Set up the endpoint URL to call (it must be using HTTPS and at least TLS1.1 or higher)
event_notification.url = 'https:\\myapp.somedomain.com'
# DocuSign will retry on failure if this is set
event_notification.require_acknowledgment = 'true'
# This would send the documents together with the event to the endpoint
event_notification.include_documents = 'true'
# Allows you to see this in the DocuSign Admin Connect logs section
event_notification.logging_enabled = 'true'
envelope_events = []
# In this case we only add a single envelope event, when the envelope is completed. You can also add events for recipients
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
So there you have it. Now you know how to add your custom DocuSign Connect webhook for the envelopes you create in your app. If you have any questions on this or any other DocuSign API related topic, feel free to email me. Look forward to my next blog post in the series next month!
