0

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

Suresh Ram
  • 41
  • 4

2 Answers2

1

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.

Inbar Gazit
  • 12,566
  • 1
  • 16
  • 23
  • True, I can just setup one endpoint /webhook/v1 and get all the information from DocuSign payload. But this is for a scenario where my listener was not even able to get to the point of processing the payload for some reasons (say unable to verify hmac signature). Using a unique ID I can track for which envelope that particular request was received. So if i have different webhooks for every envelope, any failures would be retried after 24 hours, Is my understanding correct? – Suresh Ram Jul 30 '20 at 23:12
1

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?

Matt King DS
  • 1,252
  • 9
  • 6
  • Actually I got my question after reading through the guidelines - It is mentioned that "The first retry for envelope "1" will not happen until (24 hours have passed and an additional message for the configuration for an envelope 2 succeeded.)". In my case, notification for envelope 1 goes to one endpoint and notification for envelope 2 goes to a different endpoint. So how would the retry behave? when will the notification for envelope 1 will ever be tried? – Suresh Ram Jul 30 '20 at 22:59
  • That's a really good question, and I like the unique use-case. Send an email to matt.king@docusign.com and let's get a test set up. – Matt King DS Jul 31 '20 at 23:19