Adding Connect webhooks to your application

In Part I, Webhooks: Don't Poll Us, We'll Call You!, I discussed the benefits and reasons for using webhooks to alert your app when its envelopes or recipients have a status update. In this post, I’ll discuss the steps for adding webhooks to your app.

How do webhooks work?

After you configure your webhook (Connect) subscription, the Docusign platform will initiate an HTTPS POST call to your application when a notification message is ready for your app. Usually, your app makes requests to Docusign. But webhook notification messages are delivered in the opposite direction: Docusign calls you!

There are some issues that you need to manage since webhook messages are delivered from Docusign to your app:

• Your app must include a listener HTTPS URL that Docusign can POST to. This URL must be available on the public internet; it can’t be blocked by a firewall.

• Your app must use HTTPS when receiving the POST request initiated by the Docusign production system. You can use free certificates from the Let’s Encrypt project. HTTP or HTTPS connections can be used for Developer Sandbox apps.

• Your app should authenticate the incoming messages to ensure that you’re not being spoofed. Docusign provides a number of techniques for verifying the source of its webhook messages.

Webhooks step 1: Configuring your webhook subscription

Webhook "subscriptions" (or "configurations") can be set at either the account or envelope level.

Account webhooks can notify your app anytime any envelope in your account has a status change. Whether the envelopes were sent directly from the Docusign web tool, via a mobile app, via any client app, or via the API, your app will be notified by its Account webhook.

Account webhook configurations are referred to as "Connect Configurations." Your account’s subscriptions can be set using the "Connect" screen of the Admin tool, in the “Integrations” section of the navigation pane.

Account webhooks are only available for some Account Plans. Contact your Account Manager of you want to use account webhooks and don’t see the option within your admin tool. All developer sandbox accounts include the account webhook option.

Account webhook subscriptions can also be managed programmatically through the API. See the ConnectConfigurations resource for more information. I recommend that you use the API to set your app’s Account webhook subscription. The alternative of documenting how an administrator should manually set up your app’s webhook configuration is more error-prone.

Envelope webhooks are set per envelope. The envelope is typically created by an API request, by including the webhook configuration information as an "eventNotification" section of the request. Envelope webhooks are available for all account types, they use the same underlying Connect features and message formats of the platform.

Webhooks step 2: Configuring your application

As part of your account or envelope webhook configuration, you set the listener URL for the webhook. The listener URL is a URL that your software (your "listener") receives incoming requests on. For example your listener's URL could be https://hr-app1.yourcompany.com/listener. When a change is detected in one of the envelopes being monitored, the Docusign platform will make a POST request to your listener, at the URL you provided, with the latest information.

As noted above, this means that your listener URL must be visible or "available" on the public internet to enable the Docusign platform to call it.

To accomplish this, you can install your listener on a Heroku, Amazon, Azure or private server that is available on the internet. Or you can use a service such as ngrok to tunnel the incoming requests to your machine which is behind your fire wall. Or your server can be located on your organization's DMZ, providing access to the internet. Or your firewall can be opened (a "pinhole opening") to enable the incoming notification requests from Docusign to reach your listener. You will need to work with your IT and InfoSec departments to determine the best answer for your configuration.

Webhooks step 3: Usage

Your listener should be ready to receive and process the webhook XML notification messages from Docusign.  A sample notification message for envelope completion is available. Public webhook test sites, including webhook.site can be used to see the notifications sent by Docusign. 

Configure a webhook subscription that will send update messages to your listener. Then trigger an update and see what happens. It typically takes about a minute, sometimes more, for your webhook listener to be called after the event occurred.

Webhook tips and techniques

During development, I recommend that your listener provide plenty of log information as it receives and processes the incoming notification messages.

Note that, depending on how fast an envelope’s status is changing, the Docusign webhook system may skip some intermediate status messages. For example, an envelope is sent and a signer then signs the document. This could result in four webhook notification messages, one when the envelope was sent, another when the recipient status changed to delivered, another when the recipient status changed to completed (for a signer recipient, this status indicates that the recipient signed the documents), and a fourth when the overall envelope status changed to completed.

However, if the person immediately signed the documents after opening the envelope, the delivered status notification message will probably be skipped. And since the envelope status immediately changes to completed after the last recipient’s status changes to completed, the message for the signer’s status change will usually be skipped too. Your listener’s logic should expect this situation.

Debugging a webhook listener can be tricky. Use the “Logs” and “Failures” buttons on the Administration Tool’s Connect Configurations page to debug both Account and Envelope webhook configurations. When a webhook request fails, the Failures screen also enables you to resend the notification. This can be very helpful when debugging your listener software.

Further reading

• Docusign Platform 101: Connect

• Publicly available webhook testing sites

• Webhook message format information

Questions?

Use StackOverflow with the tag docusignapi for your webhook programming questions.