Files
Introduction
Within FME Flow, webhooks are an excellent method for connecting to other applications to receive and send data in near real-time. To receive data from an external application, FME Flow uses a webhook to listen for event data to trigger a process or workflow. One of the most common ways this is accomplished is through a Webhook Trigger within an Automation, which will kick off a chain of internal and/or external actions when data is received.
Typically, the process for setting up webhooks in FME Flow is as simple as copying and pasting the Webhook Trigger URL into the external application, and then waiting for the application to push the information through the URL. However, some platforms require an additional form of verification for added security. This usually comes in the form of an initial “challenge” or “signature” from the external application, which requires an immediate response containing specific information to validate the webhook correctly. Since there is currently no way to fully configure the response sent from a Webhook Trigger, these kinds of integrations cannot be verified properly within an Automation.
This article will walk through how to use Data Virtualization to solve this issue and verify these kinds of webhooks within FME Flow. Precise implementations will vary by platform, but two examples are shown in this article:
- Monday.com webhook verification - a simple example which requires the request body to be sent back as the response body.
- Xero webhook verification - a more complex example requiring the request body to be hashed with a static key and compared to a header value. The response code sent back depends on the hashes matching or differing.
If you are unfamiliar with Data Virtualization, it is highly recommended that you complete the Data Virtualization beginner tutorial series before continuing with this article, as those tutorials cover the basics of how Data Virtualization functions within the FME Platform.
Requirements
- FME Flow, which is:
- Version 2025.1 or greater
- Publicly accessible, unless the webhook is fully internal.
- FME Form version 2025.1 or greater.
- Monday.com with a ‘Standard’ subscription or higher (if applicable)
- Access to a Xero App, and permissions to create Webhooks (if applicable)
Monday.com Integration
According to Monday.com’s webhook documentation, any application that wishes to use their webhook features must be able to echo a “challenge” string value back in its initial response. This will indicate that this is the user’s intended application, allowing Monday.com to start sending data to FME Flow. Since Data Virtualization allows users to create custom APIs to process incoming request data, it is a perfect solution for this scenario.
1. Import Project File
Download the WebhookDVProject.fsproject file from this article and import it into FME Flow. Navigate to the Projects page and select Import at the top of the Projects table. Follow through the import dialog, leaving all the settings as the default values, and select Import Project.
After the project has been successfully imported, navigate to the Data Virtualization page. You should now see a new API listed - Webhook Verification API.
2. Inspect the /monday Endpoint
Within the Webhook Verification API menu, select the POST /monday endpoint to inspect its structure. In the Details menu, we can see that this endpoint will be used to accept the challenge value from Monday.com, and that this is an unauthenticated endpoint, meaning that no credentials are required for access.
In the Request Body menu, we can see that the endpoint will accept JSON that follows the MondayChallenge schema, mimicking the format of the challenge string sent from Monday.com. Open the Schema menu to see how this simple schema is structured.
The Response menu shows that this endpoint utilizes the assigned MondayWorkspace.fmw workspace to process the request. It also shows that this endpoint will either return a 200 (OK) or 400 (Bad Request) status code, with the 200 response using the same MondayChallenge schema as the request body. This is because Monday.com expects the response body to contain the exact same information as the request body. Using the schema for both the request and response will ensure that the challenge value is being echoed properly.
3. Inspect MondayWorkspace.fmw
To inspect the workspace that processes the request from Monday.com, open FME Workbench and select Data Virtualization from the Get Started menu. Select the appropriate FME Flow connection, then select the Webhook Verification API from the API dropdown menu (if it is not already selected). Select the MondayWorkspace.fmw assigned workspace, then click Download to open the workspace.
Since we are essentially copying and pasting the request body to the response body, the workspace is quite simple:
Using a JSONFlattener and a Tester, the workspace checks to see if the request body has an attribute named challenge. If there is one, the upper AttributeCreator constructs a 200 response containing the request body. If not, the lower AttributeCreator constructs a 400 response containing an error code. This response will be sent back to Monday.com.
We can now close the workspace in FME Workbench, as nothing needs to be adjusted.
4. Test Endpoint Response
Before verifying our endpoint with Monday.com, we’ll test its functionality through the Swagger API documentation. Navigate back to the Data Virtualization page in FME Flow, select the API, then select the API Details option in the top menu bar. Select View Documentation to open the Swagger UI in a new browser tab.
Select the /monday POST endpoint to open its details, then select Try it out on the right-hand side. Specify a string value for the challenge (e.g. "testString") and select Execute.
You will see that the response we get from our API will simply echo whatever string value you have specified, confirming that our endpoint it functioning properly.
5. Verify URL with Monday.com
Now that we have confirmed that our endpoint is functioning properly, we can verify the request URL within Monday.com. Simply copy and paste the Request URL value from the Swagger UI into Monday.com when prompted. After clicking Connect, the webhook will verify for whatever automation you have selected.
6. Modify Endpoint Workspace
Since the endpoint has now been verified, we can modify the MondayWorkspace.fmw workspace to do whatever is needed with the data sent from Monday.com. This will also involve changing the request/response schemas, as FME Flow will no longer receive the challenge string value, but will now start receiving event information from Monday.com.
Xero Integration
As per Xero’s documentation, webhooks have to validate through an Intent to Receive workflow. This is similar to the process for Monday.com, but requires more complicated data processing.
1. Import Project File
Download the WebhookDVProject.fsproject file, import it to FME Flow, and open the Webhook Verification API.
2. Inspect the Xero Endpoint
In the Request Body tab, we see the endpoint expects a payload following a schema that matches the one specified by Xero. In the Response tab, we see there are three possible response codes:
- 200 and 401, for the scenarios described in Xero's documentation.
- 400, for whenever the request is ill-formed.
3. Open and Inspect the Workspace
In FME Form, open XeroWorkspace.fmw:
Look at the workspace with the bookmarks collapsed to get a high-level overview of its logic:
From this, we see the workspace generates a hash of the payload, which it compares to the hash specified in the header. If they match, it responds with a 200 status code; if they don't, it responds with a 401 status code; and if there are problems with the request, it responds with a 400 status code and error.
5. Test the Workspace
Hit run and enter the following template:
{
"body": [
{
"content": {
"entropy": "exampleEntropy",
"events": [
"event1",
"event2"
],
"firstEventSequence": 1,
"lastEventSequence": 10
},
"contentType": "application/json",
"name": "requestBody"
}
],
"headers": {
"x-xero-signature": "exampleSignature"
},
"method": "POST",
"path": "/xero"
}Run the workspace and ensure there are no errors. If data caching and feature counting are on, you should expect the following:
To test a 200 response, copy the cached value of payload_hash in the TestFilter and set this as the value of the x-xero-signature header.
6. Configure Xero and Set the Key
In Xero Developer, open an App's Webhooks page, set the Delivery URL to https://<Flow Hostname>/api/webhookverification/xero and press Save. Copy the Webhooks Key.
Go back to the workspace in FME Form. Open User Parameters and set the default value of webhook_signing_key to the key you just copied. Click OK.
7. Publish to Flow and Test
Publish the workspace to FME Flow.
In Postman or the Swagger API Docs, make a POST request to https://<Flow Hostname>/api/webhookverification/xero with header "x-xero-signature":"example" and payload:
{
"entropy": "example",
"events": [],
"firstEventSequence": 1,
"lastEventSequence": 2
}The response should have a 401 status code, with no body. See troubleshooting below if the response is something else.
8. Validate the Webhook
In Xero Developer, click Send Intent to receive. After a few seconds, the status should be OK.
Xero Troubleshooting
Misconfigured Workspace or Webhooks page.
The first thing to check when troubleshooting is that the Delivery URL is correct in Xero, and the Webhook Signing Key user parameter is correct in the workspace. See step 6 for more information.
Make sure you press Save in Xero and Publish in FME Form to make sure changes are applied correctly.
If these are both set correctly, making test requests in Postman is the best way to troubleshoot.
Missing Custom Transformer
If the endpoint responds with a 500 status code and an error about the AttributeTransposer custom transformer, verify that it's uploaded to Resources/Engine/Transformers as shown in step 7. See Sharing FME Engine Resources for more ways to upload the linked transformer.
400 Errors
These should have a helpful error message. If the message is "Invalid request body", ensure the request body is of this format:
{
"entropy": "example",
"events": [],
"firstEventSequence": 1,
"lastEventSequence": 2
}If the message says x-xero-signature is missing, make sure it's included:
500 errors
Check the job logs for the cause of these.