I am using the official DocuSign java client 3.2.0. I have set the envelope level notification as listed below. Say the webhook URL is https://A.
EventNotification eventNotification = new EventNotification();
eventNotification.setIncludeHMAC("true");
eventNotification.setIncludeDocuments("true");
eventNotification.setRequireAcknowledgment("true");
eventNotification.setUrl("https://A");
EnvelopeEvent envelopeEvent = new EnvelopeEvent();
envelopeEvent.setEnvelopeEventStatusCode("completed");
eventNotification.setEnvelopeEvents(Arrays.asList(envelopeEvent));
envelopeDefinition.setEventNotification(eventNotification);
I am trying to test the retry logic for this webhook. After few successful push requests, I intentionally made the service to return non 200 code (Example 404) for one of the request. Then I reverted the logic, so that the service continue to return 200 response for new requests.
I checked after more than 24 hours, the failed request was never retried.
Is there any reason why the request was never retried eventhough there were successful requests after the failure?
I also have a connect listener configured to push the complete notification for all the envelopes to webhook URL https://B
Currently we have come issue with this webhook URL, so all the push notification to https://B is getting failed.
Is the continuous failure with the https://B connect webhook stop retries to envelope level notification webhook https://A ?
Also Is there any difference between the connect retry vs envelope notification retries?
For for global account events (all users and envelopes) make sure "Require Acknowledgement" option is selected in your Connect settings for the specific webhook for the failed to be re-pushed.
Connect webhook is global (all users and envelopes) for the account and you can select when is triggered for example "Envelope Sent", "Envelope Voided" etc. In this way you can have multiple webhooks handling different account events.
In your case you are setting webhook notification only for the specified envelope.
Also this could help you
https://developers.docusign.com/docs/esign-rest-api/reference/Connect/ConnectEvents/
Connect retries at the account level for Aggregate Messages (the default) after 24 hours after a subsequent message is sent. I will ask about envelope-level connect retries.
Better is to switch to Send Intermediate Messages (SIM) queuing. It retries faster.
Best is to have a 100% always up listener (server). An easy and cheap (free) technique for this is to use AWS PaaS to receive and enqueue the messages. See blog post and sample code. We also have sample code for Google Cloud and Azure.
Related
If an envelope-level (vs account-level) Connect event created via the API with RequireAcknowledgement set to TRUE exhausts all retries, what happens?
In the support article, "Connect Failures and Retries", it mentions, "Administrators can choose to receive email notifications. You receive two proactive emails and another email at deactivation.". However, it seems like that applies to account-level Connect configurations, not envelope-level Connect events created through the API.
Basically, I'm trying to determine what happens after the 15-day mark, when all retries have been exhausted. Ideally, I'd receive an email notification.
After 15 days we will no longer auto-retry events and those specific events will need to be manually retried via the republish tool in the UI or with our new Republish API call.
Envelope-level Connect configurations are not being auto-disabled at this time so there will be no email notification.
Is there any guidelines/recommendations for the webhook URL that I can use for setting up the event notifications?
I am thinking of using something like this - /webhook/v1/{uniqueAppID}. The uniqueAppID changes for every envelope, I dynamically construct the URL and set it to the EventNotification object while creating the envelope.
The unique app id is used to track the response from DocuSign, So if at all there is any issue in parsing the response, I would know for which envelope/app id I have got the notification.
I read that the system will retry delivery for failures only after a successful acknowledgement is received from the webhook, In my case, it will be like having multiple webhooks. Will this setup cause any issues in retrying the failures? Does setting up the url like /webhook/v1?uniqueAppID={uniqueAppID} helps?
Thank You
Great questions.
First up, you don't have to use any kind of endpoint/URL schemes. You could have them all go one place. The information that you get from DocuSign in the payload would allow you to know everything you need about the envelope and if you need additional information - you could make API calls to determine this.
However, I would agree that if you need this information, using different endpoints would give you greater flexibility. Also, if it's different apps, you could, in theory, deploy them separately and thus the endpoint code would change without affecting other apps.
As for retry, this is done in case DocuSign does not get a 200, 201 or other HTTP response that's positive from your web server. If DocuSign gets 401 or 500 etc. If no response is received, DocuSign would retry again in 24 hours.
That should not impact your decision about the design.
One last thing to consider, you cannot be behind firewall/VPN etc. Highly recommend you consider a public cloud provider (Azure, AWS, Google) for your app to avoid networking issues.
When using envelope-level webhooks, the triggers and destination URI are embedded into that envelope. After the envelope enters a predefined state like 'sent' or 'completed', the writeback targets the URI that you provided. Unless you intentionally change this, it should remain envelope-specific.
This is different from our typical Connect setup, which would have a single URI per listener and envelopes writebacks would be directed to the listener URI at the time they're processed.
Any subsequent failure or retry attempts would follow the standard guidelines outlined here: How to get docusign webhook to retry on failure?
Currently, I am having a schedule job which get all uncompleted envelope status from my system and check each envelope status update from docusign via docusign sdk (Envelope env = envelopesApi.getEnvelope(accountId, envelopeId)). The reason to use that api is there are different use cases for each envelope status.
But I see that polling api (EnvelopesInformation envelopes = envelopesApi.ListStatusChanges(accountId, options)) has limitation that not allowed to poll DocuSign more than once every 15 minutes. I don't use this api now.
So is there any problems/limitation for envelopesApi.getEnvelope(accountId, envelopeId))?
Thanks.
The getEnvelope() and the listStatusChanges() requests both have the same polling limitation in place, if you start calling either too much your API key might get throttled or temporarily disabled by DocuSign.
However, since the listStatusChanges() request returns status on a whole set of envelopes instead of just one envelope at a time this is the preferred API request when polling the DocuSign platform.
Furthermore, the truly optimal option which doesn't count at all against the platform limits is using DocuSign webhooks to push status out to your app instead of your app constantly polling. You can configure webhooks either through the DocuSign Connect module or by using eventNofications through the envelope structure.
Learn more about DocuSign Webhooks.
What happens when the event notification is triggered from docusign and our server is down or due to network issue we didn't receive the notification. Will the docusign sends it again or we need to do the pooling.
Depending on your requiresAcknowledgement configuration of Connect
requiresAcknowledgement
When set to true, and a publication message fails to be acknowledged, the message goes back into the queue and the system will retry
delivery after a successful acknowledgement is received. If the
delivery fails a second time, the message is not returned to the queue
for sending until Connect receives a successful acknowledgement and it
has been at least 24 hours since the previous retry. There is a
maximum of ten retries Alternately, you can use Republish Connect
Information to manually republish the envelope information.
API Docs Source: https://docs.docusign.com/esign/restapi/Connect/ConnectConfigurations/get/
Is it possible to request from the API to resend a webhook?
From here i can see this is possible from the Admin Panel
https://www.docusign.com/blog/dsdev-adding-webhooks-application/
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.
I want to do the same but from the API.
Thanks!
You can use the ConnectEvents Api's.
Specifically the following api's
retryForEnvelope
Republishes Connect information for the specified envelope.
retryForEnvelopes
Republishes Connect information for the specified set of envelopes. The primary use is to republish Connect post failures by including envelope IDs for the envelopes that failed to post in the request. The list of envelope IDs that failed to post correctly can be retrieved by calling to [ML:GetConnectLog] retrieve the failure log.