From the Trenches: Bulk publish historical envelopes using DocuSign Connect
DocuSign Connect is a webhook service that enables you to receive updates when specific triggering events occur in your eSignature workflows.
To use a Connect webhook, you must set up a web service (known as a webhook listener) that is available on the public internet. When a subscribed event occurs, DocuSign Connect sends an HTTPS POST request to your webhook listener and your app uses the sent information to perform actions.
DocuSign Connect also enables you to publish messages for envelopes in your account in bulk. This is particularly useful if you need to take your listener offline for maintenance and want a mechanism to catch up quickly to missed messages. It can also be used as a way to archive all the historical envelopes in your account.
There are two ways of publishing envelopes in bulk. I will detail the steps involved in both below.
- Through the DocuSign eSignature user interface
- Through the eSignature REST API
Through the user interface
- Log in to your DocuSign account with a user who has administrative privileges.
- Select Settings in the top menu.
- Navigate to “Connect” under “Integrations” in the left nav.
- In the Connect section, select Publish > Publish using CSV.
- Here, you can upload a CSV file containing a list of envelope IDs you want to publish along with the configuration ID of the listener you would like to target.
You can publish up to a maximum of 9999 envelopes using a CSV file.
Here's an example CSV file:
EnvelopeId, ConfigurationId
59xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, 1xxxxxxxx
28xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, 1xxxxxxxx
03xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, 1xxxxxxxx
46xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, 1xxxxxxxx
How to find your Connect configuration ID:
- Log in to your DocuSign account with a user who has administrative privileges.
- Select Settings in the top menu.
- Navigate to “Connect” under “Integrations” in the left nav.
- In the “Configurations” section, all your configurations will be listed with their Configuration ID:
Through the eSignature REST API
If you have an existing integration with DocuSign, you can use the EnvelopePublish : createHistoricalEnvelopePublishTransaction endpoint to submit a batch of envelopes to a URL of your choice. It does not need to be an existing configuration on your account. This endpoint uses an ad hoc configuration to publish the envelopes requested. This endpoint only supports publishing messages in JSON SIM event model format and cannot support legacy, Salesforce, or eOriginal configurations. For legacy, Salesforce, or eOriginal configurations, you would need to use the UI as described previously.
Here’s an example request to this endpoint:
{
"envelopes": ["4280f274-xxxx-xxxx-xxxx-b218b7eeda08", "8373a938-xxxx-xxxx-xxxx-e992a2abae01"],
"config": {
"configurationType":"custom",
"name": "Test",
"urlToPublishTo":"YOUR-WEBHOOK-URL",
"allowEnvelopePublish": "true",
"enableLog": "true",
"requiresAcknowledgement": "true",
"IncludeHMAC": "true",
"SignMessageWithX509Cert": "true",
"deliveryMode": "SIM", // Send Individual message for each event.
"eventData": {
"version": "restv2.1",
"format": "json",
"includedata": ["tabs","payment_tabs","custom_fields","powerform","recipients","folders","extensions","attachments", "prefill_tabs", "documents"]
}
}
}
If the request succeeds, it returns a 201 (Created) HTTP response code, and the response body property processingStatus will be set to processing. You can then view the status of each historical republish request in the Bulk Actions Log.
Once you’ve successfully set up the request, the envelopes will be sequentially queued for processing, and you will see events flowing into your listener as soon as the processing finishes.
