Using Webhooks with fmSMS

N.B. You can also use Claris Connect Webhooks and Otto webhooks instead of the supplied PHP webhook files. If you are also a Claris Connect customer you can setup Webhooks in Claris Connect to receive incoming messages from your SMS Gateway. 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 Webhooks Using Claris Connect guide for instructions on setting up Claris Connect Webhooks for fmSMS, and the Webhooks using Otto guide for instructions on setting up Otto webhooks for fmSMS.

fmSMS includes a folder containing a series of PHP files for each supported Gateway for working with both the FileMaker Data API and the FileMaker PHP API. For each supported Gateway you will find the 2 folders like the following example for the Twilio SMS Gateway:

Inside each of these folders are a number of PHP files that you can use to receive automatic delivery status updates and incoming SMS messages as follows:

• deliveryReceipt.php: this is used to receive automatic delivery status updates from the SMS Gateway as messages are delivered. If you need to track the delivery status of sent messages you can use this to receive updates automatically from the Gateway without having to manually check on the status of individual messages
• dedicatedNumberReply.php: this is used to receive incoming SMS messages either sent in reply to an outgoing message from fmSMS or directly to your dedicated mobile number provided by your SMS Gateway
• You will need to replace the value for the $hostname variable in each of the PHP files with the IP address or DNS name of your FileMaker Server.

You will need to replace the value for the $hostname variable in each of the PHP files with the IP address or DNS name of your FileMaker Server.

To use Webhooks with fmSMS you will need to ensure the following are in place:

• your copy of fmSMS must be hosted by FileMaker Server v16 or later if you are using the PHP API Webhook files
• your copy of fmSMS 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 running PHP)
• you will need a static IP address/domain name for the web server that is part of the FileMaker Server deployment (you need to notify the SMS Gateway what the URL to the php file is that will be hosted on your Server)
• you need to install the supplied Webhooks files on your Web Server and determine the URL to each page from the outside. For example if your web server has a domain name of www.myserver.com and you create a folder called fmSMS and place the dedicatedNumberReply.php file inside the fmSMS folder the URL will be: https://www.myserver.com/fmSMS/dedicatedNumberReply.php
• some Gateways require that the URL needs to begin with HTTPS

If you’re not sure about what the external URL to the WebhooksIncomingMessages.php file is talk to your IT person – they may need to setup port forwarding on your Internet router in some cases.

FileMaker Cloud Compatibility – The only unsupported feature for FileMaker Cloud 2.x is the use of webhooks for automatically receiving incoming messages or delivery status updates. 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.

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 (HTTP or HTTPS):

[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 (HTTP): 

/Library/FileMaker Server/HTTPServer/htdocs

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 using 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.

For the Data API Webhooks you will first need to make sure that you have enabled the Data API in the FileMaker Server Admin Console under Connectors:

Once you have determined the URL to the dedicatedNumberReply.php and/or sharedNumberReply.php files you then need to update your account settings with your SMS Gateway to enable the automatic Replies option and provide the URL to these pages so they can sent the Replies for shared/virtual numbers to these pages (these will then be converted into records in the Replies table).

The process for this is different for each SMS Gateway. You can also view the details for each supported SMS Gateway from our list of Supported SMS Gateways - just click the Further details link for more information.

If your preferred SMS Gateway is not listed here please let us know – we can easily modify the dedicatedNumberReply.php and sharedNumberReply.php files for additional SMS Gateways that support this feature.

If you are having issues with Webhooks not being received successfully we recommend using Webhook.site to generate a custom URL to use as your Webhook URL and use Webhook.site to test and inspect the contents of the incoming Webhooks.

N.B. the Webhooks PHP files are not included with the trial version. If you would like to test out incoming SMS messaging with your trial version of fmSMS please contact us and we can setup a temporary hosting for the PHP file and configure it to push incoming messages to your FileMaker Server.