I am implementing a listener for Docusign event notifications. For each new event Docusign sends a new xml serialized DosuSignEnvelopeInformation object. My question is, does that object include only new changed statuses or if for example one of the recipients status has not changed it will still be included. Also, since a change to one of the recipients status does not necessarily change the envelope status, will the notification always include the envelope status ?
I'd recommend taking a look at the XSD: https://www.docusign.net/api/3.0/schema/dsx.xsd
The type sent by connect is DocuSignEnvelopeInformation, which consists of EnvelopeStatus and DocumentPDF objects, both of which have their schema defined in this XSD. In short the connect XML is a snapshot of the envelope at the time the notification is sent to you - the snapshot will include all recipient information.
In the sandbox environment you can enable a test DS Connect configuration with logging enabled to see what types of messages you will be receiving.
Absolutely correct and keep in mind that to save space in the demo environment we don't include the PDF byte stream in the log as it has no logic, meaning it's just a bunch of bytes. If you want to see it you can use webhook.com (free) or some other tool like that.
The Connect Service and the related "eventNotification" node in the API are event-driven. They don't publish events, but rather, the complete current status of the envelope, which includes envelope status, recipient status for all recipients, and more. The service always publishes the current status, so two "near" events might trigger one coalesced status publication, or two close publications. However, the last publication will include the latest changes. If you get a "republished" status (such as due to failed acknowledgement or directly triggered), it again is the current status, not the "old" status at the time of the original publication.
Related
I'm subscribed to stripe webhook charge.refund.updated event. On that event, I need to attach specific metadata to stripe refund entity (accounting needs this data in stripe exports so I need it there), but this causes same charge.refund.updated event being called again, which causes circular requests.
Only solution I'm thinking of right now is to add some kind of additional ignore field to metadata and then just ignore webhook if that value is true, but I don't really like that solution because it would persist on the refund entity, and if something actually did change on refund, my handler would ignore it.
I guess the best option would be something like stripe.refunds.update(..., { ignoreWebhook: true }), but that's not an option because API doesn't support anything like that (as far as I've investigated).
It’s recommended that you need to design your webhook endpoint to treat duplicates events. Because regardless of your circular call on Charge updates, Stripe occasionally sends the same event more than once [1]. One of the solutions: is to log the event you’ve processed and then not process already-logged events.
In your case, you can add a metadata that contains a version number of the charge. Something like this:
1 - Received an event charge.refund.updated
2- Add your logic along with another version of metadata.
3- You log the charge id, version any other field you are basing your logic while adding metadata (example: status)
4- You’ll receive another event charge.refund.updated, you check if you have already treated that charge based on what you logged already (id, version, status…)
Meanwhile, if you hit the same update charge request API [3] multiple times, only one webhook event is triggered you can test it on your own.
[1] https://stripe.com/docs/webhooks/best-practices#duplicate-events
[2] https://stripe.com/docs/webhooks/best-practices#duplicate-events:~:text=One%20way%20of%20doing%20this%20is%20logging%20the%20events%20you%E2%80%99ve%20processed%2C%20and%20then%20not%20processing%20already%2Dlogged%20events.
[3] https://stripe.com/docs/api/refunds/update
I've been working on an integration that sends an envelope to 2 signers. I am trying to test and program for the case of 1 of the signers having a bad email address. I would need to:
Be notified of this (webhook?)
Update the email address for the signer
Update the email address in the custom fields as that's printed on the agreement
Resend the envelope
When I enable the delivery failure notification in Connect (this is set up at the account level, for now), I don't see where the failure is noted in the webhook response or for which signer the error is happening.
I've found multiple links via Google talking about "correct and resend" but I haven't been able to get anything definitive in terms of what steps need to be taken or a (PHP) code example. I've also found "resend" in the API reference but still no code examples.
I also haven't seen any code examples (PHP) of how I would update a signer's email address and how that would work via the API.
It'd also be good to know how to update custom field data for both signers so the email address in the contract is updated (it's listed separately as part of the custom form data).
And finally, how would I resend the envelope?
Thank you for your thoughts.
Per DocuSign support (customersupport#docusign.com):
Be notified of this (webhook?)
I have updated your account settings and now you should be able to see AutoResponded in your webhook messages when email invalid or unreachable.
(my comments: so it sounds like you have to ask to be able to see this stuff, it's not part of their standard webhook responses)
Update the email address for the signer
I also haven't seen any code examples of how I would update a signer and how that would work.
Unfortunately we don't have an example for recipient update but the logic is to get list of all recipients, pick the one need to be updated, and update.
You can use below to retrieve all recipients per envelope
https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/enveloperecipients/list/
GET /restapi/v2.1/accounts/accountId/envelopes/envelopeId/recipients
Extract the one you need to update edit email and update using the below
https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/enveloperecipients/update/
PUT /restapi/v2.1/accounts/accountId/envelopes/envelopeId/recipients
You can also see example code in C# how to do this in this thread https://github.com/docusign/docusign-csharp-client/issues/307
Update the email address in the custom fields as that's printed on the agreement
There is bug case created ( above link ) regarding this. At the moment you can not update signer custom fields case EC-2944.
Resend the envelope
You can resend the envelope during recipient update
https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/enveloperecipients/update/
PUT /restapi/v2.1/accounts/accountId/envelopes/envelopeId/recipients
My commentary:
Since custom fields can't be updated, this whole use-case goes out the window. We can't have contracts with incorrect data on it, so my client will have to do these corrections by hand. Kind of a bummer.
I'm performing a DocuSign integration with a FileMaker solution to send signature requests via email, and receive a copy of the signed document once completed. I'm using the Java SDK to email signature request, as well as a Javalin app process to listen for the completed signature event, as well as more Java to pull the document back into FileMaker.
When the completed document is sent to my listener and pulled in, the document lacks a signature and tab field. It essentially looks just like the pdf document before being sent.
I have a feeling there's a variable I can tweak in some object to allow the signature to appear after being signed. I've played with all the usual suspects (e.g., eventNotification.setIncludeDocumentFields("true")), but nothing seems to do the trick. Any hints?
Aside from looking through the code for every object I'm instantiating and trying different variations, it's hard to pinpoint the exact source of failure in this. Thanks for any leads!
Sounds like you're receiving notifications by either including the eventNotification object in your Envelopes::create call or are using Connect at the account level. Either way, that's great, that's exactly right.
You can request notifications at many different points along the processing route of the envelope. To receive signed documents, you'll want the notification when the envelope is completed. At that point all signer recipients have signed.
To receive the notification when the envelope is complete, either adjust your Envelope Send parameters (the eventNotification value) or the settings for Connect (via the Admin tool), whichever one you're using.
I want to know if this is possible: I would like to have a custom text field on an envelope that I set and if the envelope fails for some reason, like there are missing tabs or email address is bad, I want to be able to look at the exception and see the custom field that I set. Would this info be in the raw data? It is as important to us to know which envelopes failed as to know why they failed. I saved the custom field in a database before sending out the envelope. When it fails, I can look up that custom field and discover which envelope didn't make it and to take some action, like correcting and resending.
If the envelope is created incorrectly (i.e: specifying a conditional parent tab which does not exist, syntax error, etc), then you will know at the time you attempt to create the envelope w/the API. The reason will be included in an error code the API returns
If an envelope was sent to an email address which does not exist/bounces, that information can be discovered using the DS API to see a recipient/envelope status of 'autoresponded', or if you are using DS Connect you can receive a push notification.
Is there additional rationale why you want to use a custom field? Per the above, I do not believe it is necessary or applicable.
With the RestSharp api, I was able to get the Request body. The Request body has a collection of Parameters, and one of those items is the RequestBody.
We have single connect configured for all document/recipient events.
And if we have a document that is sent to 4-5 recipients with no signing order in place.Each time a recipient signs, the 'Recipient Signed' event is triggered.
But, there is no info as to how to identify which recipient has exactly triggered the event??
Currently, DocuSign connect sends the xml response with all the Recipients' status.
Correct, if you want to know what has changed to cause a connect message to be sent to you, then you need to compare the latest message with the prior one.
Note that there can be more than one reason for a single connect message to be sent. Eg, when the last signer recipient signs, his status will be changed as well as the overall envelope status.