Webhooks are “user-defined HTTP callbacks”. They are usually triggered by some event. When that event occurs, the source site makes an HTTP request to the URL configured for the webhook.
At least that’s what Wikipedia has to say on the matter.
In this increasingly connected world WebHooks provide a way for communication between systems. Let’s take an example to help explain.
Martin works for a company that runs courses which members of the public attend. Martin wants to get feedback from those students when they complete their course, so he decides to build a survey using FormStack. Now FormStack knows what his students thought, but Martin really needs that information in his FileMaker database.
Martin could export the data manually from FormStack from time-to-time, but it would be much easier if the responses could be ‘pushed’ into his database as soon as they are submitted.
And that’s where WebHooks come in. FormStack can post the data they receive from the student to a WebHook as soon as the form is completed.
One of the great things about WebHooks is that they are a ‘push’ mechanism. It’s not necessary to check periodically to see if there are new submissions. Usually a WebHook submits a ‘payload’ – some data which comes as the result of the action that triggered it. In our example the payload would be the content of the form which the student submitted.
With FM-API.com we provide two different WebHook options. Depending on your connection type you can use one, the other, or both of them for any given WebHook submission.
With a ‘field’ type WebHook when the remote service calls your WebHook two things happen. A new record is created in the specified table, and the selected field is populated with the payload from the WebHook.
What happens to that record next is up to you. Perhaps you only need to store the information for archive purposes. Perhaps you need to extract certain data from the WebHook payload, but will do that as part of a scheduled script running on your server.
With a ‘script’ type WebHook instead of creating a record directly, a script is called. The payload of the WebHook is submitted as the script parameter. What you do with it after that is up to you. As a first step you’ll probably want to create a new record somewhere and store the parameter, but that may not be necessary.
Script processing is only currently available if your connection is using the FileMaker XML or PHP interfaces. At present the FileMaker Data API doesn’t support calling scripts – once it does we’ll update our systems to support that. ODBC doesn’t, and will never support script calls.
Record creation AND script processing
This is entirely possible, and in some situations becomes absolutely necessary.
If you’re using the FileMaker Server Data API to call the script then there’s a limit to the size of the script parameter which can be passed because of the way this has been implemented by FileMaker (using a query parameter on a GET request). This means if you’re receiving large payloads they will fail because they exceed that length (2048 characters by default on Windows, marginally longer on macOS).
To work around that we’ve made it possible to ‘chain’ the record creation to the script call, such that the UUID of the record created will be passed as the script parameter, rather than the actual webhook body.
Returning a result
Generally webhooks don’t expect to get anything other than a valid HTTP response by way of a return, but on some occasions you may wish to return something (e.g. a UUID for the record, or some other response). This can be achieved when using a script call, since the script result can be returned as a JSON payload.