In my returnUrl handler, I am using list documents.
In the returned array, how can I figure out if the document has been signed or not?
Thanks!
Your return url handler will be called with a query parameter event as discussed in Inbar's answer.
But you should not use the query parameter for making business decisions since a bad guy could easily call your return url and simply tack on an event=signing_complete query parameter--spoofing your application.
Instead, when your application needs to know if the envelope has been signed or not, it has two categories of options:
Ask DocuSign
Your app can call the Envelopes::get method to determine the current status of the envelope. Other API methods can also be used for this functionality.
Design your app such that you do not call DocuSign about a particular envelope more often than once every 15 minutes since such behavior is considered polling and is not allowed.
Webhook: DocuSign will call your app
You can set up a webhook with DocuSign so that the eSignature platform will call your application when the envelope is complete (signed by all the signers, etc).
Use the DocuSign webhook HMAC feature to guarantee that the notification message came from DocuSign (was not spoofed) and that it was not altered in transmission.
By using AWS or equivalent, you can easily receive the notification messages behind the firewall, with no firewall changes. And AWS will not charge you for the first million notification messages per month. See the connect-* repos on github.com/docusign
Dashboards
If your app wants to present a dashboard to a business decision maker about the status of your envelopes, then relying on the event query parameter is fine. But before your app does anything that costs real money, eg initiate goods or services to be provided to a customer, make sure that the envelope has been signed by using one of the two techniques above.
The URL you get back from DocuSign has an event parameter and looks like this:
http://www.acme.com?event=signing_complete
signing_complete means it was signed.
https://developers.docusign.com/esign-rest-api/guides/features/embedding has the full list of other events in the "Determining Recipient Action" section of the article.
Related
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?
Once any document is sent for signature, we can see that document status like in process, completed. Also email notification is coming to document sender mail. Are these features exposed by docusign rest API?
Yes, absolutely. The status updates are delivered to your program via a "webhook" -- you register a url with DocuSign and then DocuSign calls your app when a change occurs.
You can create a webhook subscription at the account level or for individual envelopes.
See the docs. Recipes are also available at the DocuSign Developer Center.
Added
You can also determine the current status of your signing requests (your envelopes) by polling the DocuSign platform. However, this is actively discouraged, and in any case, you can't poll more than once per 15 minutes for a given envelope. The docs discuss this as well.
I have successfully implemented a system that creates documents to be signed via a template using the .NET API, and then has a DocuSign Connect listener that gets called upon the envelope being signed (right now only have Connect reporting on envelope signatures and declines). I have the option set to "Include Documents" on my DocuSign Connect settings. When I create the envelope for signature programmatically with one signer it all works - my Connect listener gets called, the /DocuSignEnvelopeInformation/DocumentPDF/PDFBytes element has Base64 data in it, and I have successfully decoded that and stored it in our doc management system. Cool. Demos well, management loves it.
However, I have noticed at least two scenarios where the /DocuSignEnvelopeInformation/DocumentPDF section isn't being returned at all:
When there are multiple signers.
When the envelope is created manually, even if it uses the same template.
I can still use the Connect response to get the /DocuSignEnvelopeInformation/EnvelopeStatus/DocumentStatuses and extract the document IDs from the DocumentStatus child elements, and then go retrieve those programmatically using the .NET API. But I am wondering why the PDF bytes aren't being consistently returned all the time? Is the above expected behavior? Am I missing something?
I would prefer to save "round trips" and just have Connect deliver all the signed PDFs to me when it calls (and yes, I have read the Recommendations for Receiving Documents section of the DocuSign Connect Guide and understand the trade-offs. Just wondering if I need to code around this issue, or what I am missing?
Hmmm. Envelopes don't get "signed," they get "sent" and "completed." See the envelopeEvents vs the recipientEvents lists in the Connect::Create call.
Currently, there is an existing issue which is that the connect daemon can miss an event if it is quickly superseded by another event. This might be what is happening when you have multiple signers for an envelope. The safest thing to do is to subscribe to all events and then ignore the notifications that are not of interest to you.
The terminal event of an envelope being "completed" will always be sent if you've subscribed to it.
Also, to make your app more bulletproof, I suggest subscribing to the Connect events via the API call (link is above) rather than depending on the human to setup up the subscription correctly. Since an account can easily have more than one connect subscription, you can track which one is your app's by using a specific name for the subscription.
Added
Just now, I created a Connect subscription for just the Envelope Completed event, for all users in my account on demo.docusign.net. As the subscription (listener) url, I used a free account from requestb.in
Using the web user interface (not the API), I created an envelope with two signers. After I completed the envelope, the requestb.in received the notification, it included:
<DocumentPDFs>
<DocumentPDF>
<Name>House architectural overview.pdf</Name>
<PDFBytes>....
as expected. So I'm unable to reproduce your problem. I suggest that you use requestb.in to double-check exactly what is being sent in the notification messages.
I am using Stripe and I need to understand how to only process webhooks that are generated by Stripe behind the scenes. When my server sends something to Stripe (new subscription, new individual charge) Stripe will generate events that are sent via the webhooks I provide. Well, I don't need to process those since it will create a mess. I only want to process Stripe generated webhooks in situations like: failed charge at subscription renewal, manual modifications via the Stripe dashboard, refunds generated in the dashboard, etc).
I went through the events generated and I cannot find anything that would make a difference from those my API calls generate or those generated behind the scenes.
Is there something I am missing?
Update
- API call: event has a request id
- Stripe behind the scenes: event has null request_id
- Stripe dashboard: event has a request id (This still remains a problem)
If I discard all webhook events that are not null I will also discard Stripe dashboard events. I need to process Stripe behind the scenes and also Stripe dashboard generated events.
First of all, Stripe currently does not support identifying the incoming webhook event type. Looking in the Dashboard I indeed can see what initiated the event (API, Dashboard or Automatic) but Stripe's people said they don't support it.
However, there is a workaround. For anyone struggling with this I will describe what I did. An automatic Stripe generated event is easy to differentiate. It contains a null request field. Any other type of event will have a request id (ex: re_123h2kj18321hjk3218). The problem remains with differentiating between API and Stripe Dashboard generated requests. Therefore, the solution is to capture the request id for every request generated by the API. Whenever a webhook arrives to your server, you check for the request field NOT to be in the Storage System (DB, etc) OR that the request is null. This means that the event was generated by either the Dashboard or Automatically by Stripe (subscription renewal).
Steps:
Hook into the CurlClient provided by Stripe. Extend that class and
override the request() method. The request method returns the
response generated by Stripe servers. Capture the headers of the
response which would contain a Request-id. Store that in your
Storage (in my case a DB)
In your configuration files you need to specify that Stripe should use your own CurlClient. ApiRequestor::setHttpClient(new CurlClient()); (I've named my CurlClient too but you can name it whatever)
When a webhook arrives, you have three options to identify the type:
Automatic: if the event has a request=null
Dashboard: the request is not null and the request is not in you Storage
API: you're left with one situation. The request is not null but exists in your DB
As you can see, there's quite a lot of work for something really easy. All Stripe needs to do is provide another field in their webhook event name something like request-type with three options (api, automatic, dashboard). They already have this build but they don't allow it to be shown in the webhook event.
On the event object documentation, you'll see the request property documented. This property is set whenever the event came from an API request. Otherwise, if it's null it means there was no API request associated with it and it was what we call an Automatic event in the dashboard.
You need to discard any event where request is not null on your end!
There is a documentation about possible envelop status value from docusign for a given envelope.
Howver i am trying to understand if there are any documentation which lists out the possible "Action" value from docusign in the "Audit_event" REST API method.
The reaosn is I am storing the audit events locally to avoid multiple API calls and i wanted to account for all the possible action values.
Thanks for reading
Since there were any documentation provided, i am including the staus i have seen based on my reverse engg
Registered
Sent Invitations
Printable Copy Delivered
Printable Copy Attached to Email
AccessCode Passed
AccessCode Failed
Viewed
Signed
Approved
Resent
Voided
Declined
Correction Initiated
Correction Cancelled
Viewed In-Session
Corrected
I've never seen any documentation for possible values of the action property within a GET Envelope Audit Events response -- to the best of my knowledge, none exists. You might be stuck having to 'reverse engineer' to determine possible values. i.e., create envelopes via the DocuSign web console, act on them in a variety of ways (both as Sender and as Recipient) -- for example: Send Envelope, Void Envelope, Decline Envelope, Sign Envelope, View Envelope, Pass Signer Authentication, Fail Signer Authentication, etc. etc. etc. -- and then examine the corresponding action values that appear in the GET Envelope Audit Events response for those Envelopes.
Obviously this approach is not ideal, since someone fairly new to DocuSign won't necessarily know all of things that can be done with an Envelope, in order to trigger the various action values in the API response. Perhaps someone from DocuSign will see this post and chime in with a list of all possible values...or better yet, add this info to the API Guide one day soon.