Using a webhook to track envelope status
This recipe enables your app to monitor status changes of your envelope and its recipients without polling the DocuSign platform.
To use the example code you will need:
- A DocuSign developer account email and password.
- An integration key. See Generate Your Integrator Key.
- The DocuSign client library for your software language.
Try it out!
The recipe source files include a full example that enables you to send an envelope with a webhook set, and monitor the incoming notifications as they are sent to you from DocuSign. You can run the example, for free, on Heroku or Microsoft Azure.
Run the recipe on Heroku
Deploy the recipe to Heroku. Enter your DocuSign Developer Sandbox credentials on the form in the Heroku dashboard. Then press the View button at the bottom of the dashboard screen when it is enabled by the dashboard.
For more information, see the Heroku section of the PAAS recipe.
Run the recipe example on Microsoft Azure
Start with the Microsoft Azure section of the PAAS recipe.
At Step 6, cloning the example's Git repo, the Repository URL is
Step 7. Check that the editor is in EXPLORE mode, so you can see the example’s files:
If not, click the file explorer icon.
Next, click on the web folder name to open it.
Click on the file 010.webhook_lib.php to open it in the main window of the editor.
Update lines 9, 10, and 11 with your DocuSign Developer credentials instead of the asterisks. The file is automatically saved.
Step 8. Try out the example.
How to do it
Step 1: use the login_information API end point to obtain the base url for use in subsequent API calls, and the user’s account ID. See the recipe Requesting a Signature via Email for an example of this step.
Step 2: Use the Envelopes:create method to create a new envelope. When you create the envelope, include an eventNotification object with your call. Specify the URL of your webhook listener by setting the eventNotification url property.
Step 3: In this step, when your listener is called by DocuSign, it examines and processes the incoming webhook data.
For this example, the notification’s EnvelopeID and TimeGenerated fields are used to create a unique filename for the notification. The XML notification is then stored on the server’s filesystem for further processing.
If the envelope status is "Completed," then the signed pdf files are extracted from the XML file.
Additional language versions of the recipe are in development and will be posted here in the future.
How it works
Instead of using the more common web pattern where your app calls a web server, this recipe uses the webhook pattern: Your app accepts push calls from the service provider. After you define your webhook, the DocuSign platform calls your application when the envelope status changes.
Since DocuSign is calling your app, your app needs to be accessible to the general internet.
When you add your webhook, you can define the DocuSign events that will cause your webhook to be called. Eg, you can decide that your webhook is called for any envelope status change, or only when the envelope has been completed. You can also set DocuSign to include the envelope’s documents when DocuSign calls your webhook.
DocuSign calls your webhook with a notification XML file. Notification files contain the latest information about your envelope and its recipients. Example XML notification files: envelope creation, envelope completion.
The Templates: Create method also accepts an EventNotification object. This enables templates to include your webhook settings.
Who’s calling? To ensure that it really is DocuSign that is calling your app, you can check the SSL/TSL certificate of the webhook caller (DocuSign). You can also set DocuSign to digitally sign the data in the notification XML.
The eventNotification webhook feature used in this recipe is available for all customers who use the API to create envelopes.
If you wish to use a webhook to track envelopes that were created by users through the DocuSign web interface, see the Connect API feature. Connect is not included with all pricing plans, please discuss your needs with DocuSign Sales. Your Developer Sandbox Account does include access to the Connect feature for development and testing.
Webhooks behind the firewall: Talk to your firewall team about adding an exception in your firewall for just the incoming webhook calls from DocuSign. DocuSign publishes the IP address ranges that are used to call customer’s servers, enabling fine-grained firewall access.
Another option is to host a machine on the internet that only receives the incoming webhook calls from DocuSign. Your app can then poll the first machine as often as you like.