⭐ Available on the following plans: Pro & Agency (limited), Business
👀 Not sure which plan you're on? Check your subscription here.
A webhook is a way for your Heyflow to send information instantly to another service or application when someone submits a response. Think of it as an automatic message that notifies another system about the new submission, allowing you to process the data in real-time. Heyflow allows creating custom webhooks that send every submission straight to any URL endpoint that receives the response data in a JSON format.
In the business plan, there are numerous customization options available to tailor the webhook to your requirements.
This article covers:
Creating and testing a new webhook
Navigate to the Integrate tab and select Hooks.
Provide a valid URL and assign a name to the webhook for easier identification.
Click Test to send an example payload to the specified URL.
Test Webhook payload
{
flowID: <YourFlowID>,
id: 'demo-response-id', // Heyflow UUID for the response
createdAt: new Date(), // datetime of the test trigger,
fields: {
'Demo Field 1': 'Some value', // 'Demo Field 1' is your system label,
'Demo Field 2': 'Some other value',
},
}
After a successful test (HTTP status code 200), activate your webhook. From now on, each new submission will be sent to the specified URL.
Customizing Your Webhook (Business Plan)
If you're on the Business plan, you have additional options to tailor your webhook:
HTTP Methods: Choose how the data is sent (POST, PUT, or GET).
Custom Headers: Add specific information required by the receiving system.
URL Parameters: Include fixed details like API keys in the webhook URL.
Basic Authentication: Secure your webhook with a username and password.
Extended Payloads: Receive more detailed information about each submission.
Simple Webhook Payload
This is the standard format sent with each submission:
{
"flowID": "<YourFlowID>",
"id": "<HeyflowResponseUUID>",
"createdAt": "2025-04-24T11:18:55Z",
"fields": {
"System Label": "Value"
}
}
❗ Please note: If you want download links to be full file URLs from which you can programmatically download the files, make sure to enable Public Link access for the flow in the settings.
Extended Payload (Business Plan)
If you're on the Business plan, you can also send an extended payload. This format is useful if you need detailed context about each field. Most importantly, the type of fields changes from being an object to an array of objects.
{
flowID: <YourFlowID>,
id: <HeyflowResponseUUID>, // Heyflow UUID for the response
createdAt: <DateTimeOfTheResponseSubmission>, // new Date()
fields: [
{
// Each block has a static unique identifier, the ID:
"id": "mco-fb5cd9b5",
// The label is either the system label or block label you define:
"label": "Please choose an option",
// The values holds the user entered data in an array. If only one
// value can be specified, e.g. an input field, it only holds one
// object. If mutliple values can be speificed, e.g. for a Multiple
// Choice block, it holds multiple elements.
"values": [
{
"name": "mco-fb5cd9b5",
"answer": "Option 2 label"
}
],
// The variable you have specified for this block.
"variable": "mc-24115746",
// If this block is flagged as senstivive as a boolean.
"sensitive": false,
},
],
}
❗Please note: The structure and content of the extended payload are predefined by Heyflow and cannot be customized. You can include additional information by adding hidden input fields to your flow. These fields can capture extra data (e.g., tracking parameters, user metadata) and will be included in the payload upon submission.
Adding (fixed) URL Parameters:
You can append fixed parameters to your webhook URL:
Example:
Original URL: https://www.example.com/webhookparty
With URL parameters: https://www.example.com/webhookparty?clientID=12345&apiKey=abcdef
❗Please note: Dynamic data from user inputs or flow variables cannot be used in URL parameters.
Tracking URL parameters
If you want to pass URL/UTM parameters from your flow to your webhook, you need to set up a hidden input field to capture the data. Once set up, you can map these input fields to corresponding fields in your response handler of choice.
The UTM parameters will then be automatically passed along with each response—without your visitors noticing. 🚀
Error Status Codes
As soon as we detect a problem with your webhook integration, we will send you an email with the flow ID and the error status code (HTTP status code) The message will look something like this: Error: Request failed with status code 503.
In this example, you are receiving an error because the server cannot be reached and is temporarily unavailable.
We receive these error codes from the URLs or servers that you use in the integration. We therefore only forward the error.
🔎 For an overview of the error codes, take a look here.