fmESignature Link (DocuSign Edition) Webhooks and Server Schedules

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.

N.B. You can also use Claris Connect Webhooks and Otto webhooks instead of the supplied PHP webhook files. If you are a Claris Connect customer you can setup Webhooks in Claris Connect to receive incoming notifications from DocuSign. This is usually a much simpler process than using the supplied PHP files for the FileMaker Data API as you don't need to worry about hosting the files and dealing with web servers, PHP configuration changes, port forwarding etc. 

Please visit the DocuSign Webhooks Using Claris Connect guide for instructions on setting up Claris Connect webhooks for DocuSign, and the DocuSign Webhooks using Otto for instructions on setting up Otto webhooks for DocuSign.

N.B. In v1.4 of fmESignature Link we changed from using XML as the data format for the webhooks to JSON notifications once this became available.

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 - support for the Data API was added in v1.25). If you are using FileMaker Server you can use either the PHP API files or the Data API files - we recommend using the Data API where possible.

If you are using FileMaker Cloud for AWS you can use the Data API versions of the Webhooks files. The Data API Webhooks currently don't work with FileMaker Cloud 2.x deployments due to the differences in how authentication is handled for FileMaker Cloud 2.x users with the Data API. We hope to have a version of the Webhooks that support FileMaker Cloud 2.x soon.

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.

N.B. In January 2021 Claris announced that Custom Web Publishing with PHP is being deprecated and they are making changes to how PHP is bundled with FileMaker Server. Please see this support article for further details.

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.

N.B. on Windows you will also typically need to make some changes to the default php.ini file for the PHP files to function correctly - see this article in our FAQ for all the details.

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.

Still need help? Contact Us Contact Us