DocuSign Webhooks using Otto

Otto from Proof+Geist can be used to receive webhooks from DocuSign and automatically download the completed PDF when it has been signed by all parties. You will need to make a few small modifications to your copy of fmESignature Link (DocuSign Edition) - we've added support for Otto webhooks in v1.55 of fmESignature Link (DocuSign Edition). 

If you're using an earlier version of fmESignature Link the required changes are outlined on the Otto website here and include creating a new layout, 2 new fields and 1 new script. You can copy/paste the OttoReceiver script from the v1.55 file to your file. Your new OttoReceiver layout (based on the Webhooks table) should look like this:

In the following example we will show you how to create an Otto webhook to receive completed agreement notifications from DocuSign (similar to the webhookSignedEnvelope.php file). We will be using the optional eventNotification object that you can use to add a Webhook to the DocuSign envelope that will automatically send updates to the fmESignature Link file when certain events happen within DocuSign.

N.B. DocuSign only deliver webhooks to specific ports ending in 443 (443, 2443, 3443, 4443, 5443 etc) which means you will need to change the default port Otto uses (3030). There are 2 workarounds for this currently:

1. you can change can change Otto's port to 8443. This means that you use this new port number when accessing Otto. You can find instructions for modifying the Otto port number here.
2. you can modify the http config to remove the need to use a different port for Otto's API. Instructions for this will be available soon.

Once you've made the necessary changes you need to create a new Otto Data API key by following the instructions here. We recommend using the supplied OttoDeveloperAPI.fmp12 FileMaker file to create the key which only takes a few minutes. When creating the Data API Key you can use the same FileMaker account that the webhookSignedEnvelope.php file uses here as it has the required access privileges for receiving incoming webhooks via the Data API:

Once you've generated the Data API Key for the fmESignature Link file you can make a note of the URL for the DocuSign webhook. We are using the query parameter option to handle the authentication. The webhook URL should look something like this:

https://otto-server-url:8443/receiver/fmESignature Link (DocuSign Edition).fmp12/docusign?apiKey=<your-api-key>

This is the URL you will enter in the Completed Event Webhook field when sending a Request - DocuSign will send a notification to that URL when the Envelope has been completed which will create a new record in the Webhooks table, the EnvelopeID field will be populated with the DocuSign Envelope ID and the Data field is populated with the complete body of the webhook JSON data and then the OttoReceiver script is performed which downloads the completed PDF. 

You can also enter this URL into the Completed Event Webhook field for the Template record so you don't need to enter this for each Request:

You can now test this is working successfully by sending another test Request to yourself from the fmESignature Link (DocuSign Edition) file - remember to enter the Otto Webhook URL in the Completed Event Webhook field. Once you have completed signing for that request you can monitor the request and see if the Signed PDF and Envelope Status fields are updated automatically – this normally happens in under a minute in our experience. Each Webhook that is sent by DocuSign should also create a new record in the Webhooks table record which you can view by navigating to the Webhooks layout via the layouts menu.