DocuSign webhooks sends 1 envelope per message. It can also return the respective child entities if they have been configured so (e.g. documents, recipients).
I wanted to receive audit events of the envelope (when someone opened or viewed) in the message as well.
Is it possible? Or is it only possible through polling? What is the recommended strategy?
The DocuSign webhook notification messages are sent per webhook event. There are events at the envelope level (Draft, Sent, Delivered, Completed, Declined, or Voided) and for each recipient (Sent, Delivered, Completed, Declined, AuthenticationFailed, and AutoResponded).
The audit event of a recipient viewing an envelope is available as the Delivered recipient event.
There are other audit events which are not available as webhook events. To track those you'd need to poll. Remember the DocuSign limit of polling no more often than once per 15 minutes per envelope. (And the overall API limit of 1,000 calls per hour.)
If you subscribe to the recipient.Delivered event then you'll receive a webhook message when a recipient views the envelope. See the Delivered date stamp for the recipient and the Delivered status.
BUT if you have the webhook system set to aggregate notification messages (the default) then individual notifications may be aggregated together. For example, if you're subscribing to both the recipient delivered and completed events, and a recipient opens (delivered) and then immediately signs (completed) the envelope, you may only get one notification, for the later (completed) event.
But your code can look for the delivered date stamp to see if the envelope was delivered.
Related
Our application is able to use DocuSign REST API to create an envelope for users to sign, and return the signed document to our application once the signing is done.
Recently, the issue is when the document signing has been completed, it is always missing the last signature. For example, we have indicated 3 signers to sign, but in the completed document it only shows 2 signatures.
The missing signature problem only happens to the completed document that is pushed back to our application. When the signers receive the signed document via DocuSign's email, all 3 signature are in the attached signed document.
Please let us know if there is any change to any API recently that cause us to face this issue, or what configuration do we need to fix. Thanks!
You say that your DocuSign "return[s] the signed document to our application"
If you're using Connect or the eventNotifications attribute for this, then you're using the DocuSign webhook system. Check that the webhook events you're interested in only list Envelope Complete. Not Recipient Complete.
Also check if the status of the envelope itself is complete. You've not indicated whether the problem is that the last signer is not asked to sign or if you're receiving a notification before the last signer signs.
If you're using a template, check that the template has not been changed and works as expected when it is sent from the DocuSign web app (vs the API).
Added
In the comments, the OP notes that they:
are using Connect webhooks
are requesting notifications for both Recipient Complete and Envelope Complete
In addition, from the question, I believe that the developer is using the default Aggregate queuing method.
What's happening
When aggregate queuing is used, notifications are initiated when a requested event occurs. But if a second requested event occurs before the notification from the first event is sent, only one notification will be sent for both events, and the notification content will reflect the later (the second) event.
So what is usually happening:
The last recipient signs (completes)
The recipient complete event triggers a notification. It is not yet sent.
The envelope as a whole becomes complete milliseconds after item 1.
The envelope complete event is triggered. The recipient complete notification has not yet been sent.
The notification is actually sent. The notification includes the envelope complete information.
What will sometimes happen:
The last recipient signs (completes)
The recipient complete event triggers a notification.
The DocuSign system sends off the notification. It shows that the recipient is complete but not the envelope.
The envelope as a whole becomes complete.
The envelope complete event is triggered.
The notification is sent. The notification includes the envelope complete information.
Conclusions
If you are only interested in the envelope complete status (everyone signed) then do not request the recipient complete events!
If you want recipient complete and also want envelope complete events, then your application needs to inspect the incoming notification to determine the envelope's status.
Added re why not recipient_complete?
recipient_complete events should only be requested if your application will take action as each recipient in the envelope completes. (A signer is complete when they sign, a cc recipient is complete when the email has been sent to them, etc.)
If your app will only take action when the envelope as a whole is complete, then asking for recipient_complete events too will only cause additional notifications that can be confusing to your app's logic.
In my DocuSign application, I have two recipients that sign documents. When both recipients finish signing the envelope, DocuSign Connect dispatches two identical XML payloads, at what appears to be exactly the same time. This causes issues with my application because I don't want my logic to be duplicated. Is this is a bug in the DocuSign Connect, or is it intentional? I don't think DocuSign duplicated calls when I set up my application two years ago.
Here's an example envelope that appears in the Connect logs in my account:
First webhook call
<TimeGenerated>2020-04-13T10:34:19.1110424</TimeGenerated>
Second webhook call
<TimeGenerated>2020-04-13T10:34:19.1110424</TimeGenerated>
If you're requesting recipient completion events then you shouldn't be surprised to get two notifications, one for each of the two recipients.
They can be the exact same since the default queuing strategy for Connect is for the notification message to reflect the envelope's status at the time the notification is sent, not the status at the time the event triggered.
Suggestions:
Switch to the new queuing strategy, SIM (Send Intermediate Messages). Do this from the Admin tool, in the Updates section.
Only request the envelope completion event, not the recipient completion event.
Update your app to more flexibly handle the notifications. Note that with the default queuing strategy, a recipient completed event will often be skipped in favor of an envelope completion event (if you're asking for both envelope and recipient completion event notification).
The status for the voided envelope is "sent" in the XML POST response for the webhook listener. The document pdf bytes are also in the "sent" status . But the envelope is showing as "void" in the docusign account and the documents are voided too .# Inbar Gazit
You may need to open a case with DocuSign Support and provide specifics such as your account ID and the envelope ID in question.
Are you using an account-level Connect configuration, or are you using an envelope-level EventNotifications definition? Either way, you'll want to confirm what events are set to fire. If you haven't enabled the 'Voided' event, it won't fire.
Are Logging and Require Acknowledgement enabled? If so, you can check the Failure queue to see if the event fired, but was rejected by your listener. Logging will show which events have fired, as well.
Finally, you can use a free service like https://webhookapp.com/ or http://webhook.site to confirm that the data coming from DocuSign matches what you're expecting.
Is there such thing for eventNotification envelopeEvents to have signed event? I'm using webhook.
I see 2 differents documentation here.
Basically I needed to know when the document has been signed, but it's not ready to be downloaded yet, so I can show that the document is in Pending State on the UI.
I need this, since if the user close the docusign page, it will count as, declined or void. So I can't use that event status to trigger any event.
Note:
I have it already working with webhook, for completed event.
It's just sometime after the user signed everything.. It takes up to 5 minutes for the document to be available from docusign (completed event). Thus I need some way to show the user on the UI, that it is already signed, but not available yet (PENDING state)
Instead of a signed event, DocuSign uses the Completed event.
Why: completed covers the different situations for the different types of recipients--
a signer recipient is complete when they sign the document.
a carbon copy recipient is complete when the email with the copy is sent to the recipient.
a certified copy recipient is complete when they positively acknowledge receipt of the copy.
Etc.
There are also two levels of webhook notification available to you:
You can be notified when the entire envelope is complete. This is when all the signers for the envelope have signed.
You can be notified when each individual recipient has completed their action. This means that you'll also be notified when non-signers have reached the complete status.
You can also elect to receive both sets of notifications. (And more.)
Note that envelopes don't need to have any signers. You can examine the webhook notification message and/or interrogate the envelope's status to determine exact status after you've been notified via the webhook.
A sender has an option to discard an envelope.
I'd like to get a notification when that happens. So I subscribed to "Voided" event but have not been able to receive notification from the Docusign connect when sender discards an envelope.
Any feedback is appreciated.
Roman
Are you referring to the Discard Changes action, as shown here?
If so, there is no DocuSign Connect event notification that correlates to this sender action.
If the Sender were to click Discard Changes in the process of creating a new Envelope (i.e., one that hasn't yet been saved or sent), there wouldn't be an envelope to associate the event notification with (because the Envelope ID isn't created until it's Saved or Sent).
If the Sender were to open an existing Envelope via the DocuSign UI (i.e., either a Draft Envelope that has never been sent or an In-Process Envelope that is pending action from one or more recipients) and click Discard Changes before sending or saving, there wouldn't be any Connect event notification triggered because there was no change in Envelope state.