The DocuSign API includes an optional eventNotification object that you can use to add a Webhook to the envelope (document signing request) that will automatically send updates to the fmESignature Link file when certain events happen within DocuSign. We’ve included support in fmESignature Link (DocuSign Edition) to automatically receive the completed PDF when it has been signed by all parties using the eventNotification Webhook.
This is the most efficient way of retrieving the completed PDF from DocuSign as you don’t need to be continually polling DocuSign for updates to each outstanding signing request – DocuSign limit polling for updates for the same envelope to no more than once every 15 minutes.
fmESignature Link (DocuSign Edition) includes a ‘webhooks’ folder that you can upload to your FileMaker Server (or web server) that contains a number of PHP files that can be used to process incoming Webhook notifications from DocuSign when a document has been completed. It can also be used with FileMaker Server schedules if you cannot use Webhooks and would like to poll DocuSign for any completed PDFs to save having to manually check for updates.
There are 2 ‘webhooks’ folders for use with either the FileMaker PHP API or the newer FileMaker Data API (the Data API requires FileMaker Server v17 or later).
To use Webhooks or Server Side Schedules with fmESignature Link you will need to ensure the following are in place:
- your copy of fmESignature Link must be hosted by FileMaker Server v16 or later if you are using the PHP API Webhook files
- your copy of fmESignature Link must be hosted by FileMaker Server v17 or later if you are using the Data API Webhook files
- you will need to deploy and configure Custom Web Publishing with PHP if you are using the PHP API Webhook files
- If you’re using the Data API Webhook files you will need to enable the Data API and host the PHP files (either on your FileMaker Server or elsewhere, for example Amazon Lightsail or your own web server)
- you will need a static IP address/domain name for the web server that is part of the FileMaker Server deployment (we need to enter the URL to the webhookSignedEnvelope.php file that will be hosted on your Server in the appropriate Template/s)
- you need to install the supplied ‘webhooks’ folder (either the PHP API or the Data API version) on your Web Server and determine the URL to the webhookSignedEnvelope.php file contained in the webhooks folder from the outside. For example if your web server has a domain name of www.myserver.com and you create a folder called fmESignatureLink and place the ‘webhooks’ folder inside the fmESignatureLink folder the URL will be: https://www.myserver.com/fmESignatureLink/webhooks/webhookSignedEnvelope.php
- the URL needs to begin with HTTPS: DocuSign only support HTTPS Webhook URLs.
If you’re not sure about what the external URL to the ‘webhooks’ folder is talk to your IT person – they may need to setup port forwarding on your Internet router in some cases.
The web server “root” folders for the installation location of the PHP files for FileMaker Server v16 and later is:
Windows:
[drive]:\Program Files\FileMaker\FileMaker Server\HTTPServer\Conf
where [drive] is the drive on which the Web Publishing Engine component of your FileMaker server deployment resides.
Mac OS X (HTTPS):
/Library/FileMaker Server/HTTPServer/htdocs/httpsRoot
N.B. the HTTPS options require a valid SSL certificate to be installed. If you are using FileMaker Server v17 or later you cannot use the FileMaker Server Admin Console to enable Custom Web Publishing using the PHP API. You will need to use the Command Line Interface to enable these – see the FileMaker Server 17 Help for more information on these commands.
Once you have determined the URL to the ‘webhooks’ folder and the webhookSignedEnvelope.php file you need to enter these URLs into the URL to Webhooks Folder in the Setup screen:
and the Completed Event Webhook field in the Template Details layout for any Templates that you wish to add the Webhook notification to (not required for Server Side Schedules):
When the Webhook makes a successful request it performs the following actions:
- it updates the Status for the matching Envelope ID to ‘Completed’
- it downloads the signed PDF file into the Signed PDF field
Once you have the URLs you can send yourself a signing request to confirm the Webhook is working. 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 layouts via the layouts menu:
We have a video demonstrating the DocuSign Completed Webhook in action on the fmESignature Link Videos page.
Server Side Schedules
The fmEcommerce Link file includes a script that you can schedule using to be run no more than every 15 minutes (we recommended every 20 minutes to be safe) called Check for Completed Documents [SERVER]. Simply schedule this using the FileMaker Server Admin Console and it will then start checking for any documents that have changed to the ‘completed’ status within the last 20 minutes and download the completed PDF automatically.