Webhooks are commonly used for exchanging information between different applications. Heyflow allows creating custom webhooks that send every submission straight to any URL endpoint that receive 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
Simple Webhook Payload
Extended Webhook Payload
URL parameters
Error Status Codes

Creating a new webhook

Go to the Integrate tab and navigate to Hooks.
After providing a valid URL, you will be able to set a name for the webhook for easier identification.
Upon clicking test, we will send an example body with the following format to the URL. Keep in mind, the structure is an example, but the fields property does not contain actual fields from the flow.

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 (the supplied endpoint returned an HTTP code 200), you can activate your webhook. Now, every response will also be sent as a post request to the URL.

Customizing a webhook

If you are a business plan customer, you have plenty of customization options to make webhooks work in a multitude of scenarios.

First off, you can customize the type of HTTP request being made. Secondly, you can supply custom HTTP headers that might be required by your endpoint. Thirdly, in addition to the response data, you can supply custom URL parameters like API-Keys or similar. Lastly, we also allow adding HTTP Basic Auth credentials.

In addition to these options, you also have the choice to extend the data structure. Below, you can see the difference in the payload to decide which is more applicable for your use case.

Simple Webhook Payload

Normally, the webhook payload contains a fields object. In this object, the keys are the system labels defined for the fields in the flow, and the value corresponds to the answer given by the users.

❗ Note: If you want download links to be full file URLs from which you can programmatically download the files, make sure to turn on Public Link access for the flow in the settings.

{
  flowID: <YourFlowID>,
  id: <HeyflowResponseUUID>, // Heyflow UUID for the response
  createdAt: <DateTimeOfTheResponseSubmission>, // new Date()
  fields: {
   "System Label": "Value" 
  },
}

Extended Webhook Payload

In the extended webhook payload, we provide a lot of additional metadata for the fields property. 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,
    },
  ],
}

URL parameters

You can add URL parameters, that are attached to the webhook URL, e.g.

Your webhook URL is https://www.example.com/webhookparty.

If you add your URL parameters, we would send a request to https://www.example.com/webhookparty?test01=4711&test02=4812

You can use this feature for fixed parameters. Imagine you are sending a webhook to some lead ingestion engine. These usually have a fixed clientID of sorts, that is something you would put here. Another example would be API keys.

❗ Note: You cannot use flow variables or any data that was entered into the flow in the URL parameters.

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), e.g.

Error: Request failed with status code 503.

In this example, you receive the 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.