Webhook Actions
Configuring a form action to interact with an external service via webhook
The Webhook action connects Form submissions into other applications or databases by providing a means to call an external API with a payload containing the form submission data in real-time. In order for the Webhook action to function properly, the API endpoint must be accessible by the same network as the Form.io deployment.
Webhooks execute when using a form. They do not execute when building/editing a form within the Developer Portal. To test Webhooks, the form should be launched using the FormviewPro Application, or embedded within an application.
Settings
Request Method: This is the REST Verb that will be used to make the request. If set to Match (or blank) it will use the request method that came with the request. For example, a Create request will have the Post method. Below are the available request methods:
Get, Post, Put, Delete, Patch
Request URL: The URL of the external system that will handle the webhook. This should be accessible to the form.io server.
Forward Headers: If checked, all of the headers received by the form.io server will be forwarded to the webhook.
Authorize User: If you are using Basic Access Authentication for the webhook request, enter the username here.
Authorize Password: If you are using Basic Access Authentication for the webhook URL, enter the password here.
Additional Headers: You can add additional headers as needed by providing the Header and Value. These might include an Authorization header or Content-Type.
Request Payload: By default, the request payload will contain an object with the following information:
You can use the transform payload javascript to modify the contents of the payload that will be sent in this webhook. The following variables are also available: headers
Transform Payload: You can modify the request payload by writing custom javascript code. There are available variables that can be used to aggregate into a custom object as desired. Whatever is placed into the payload will be sent as the body of the request.
Wait for Webhook Response
By default, webhook actions will not wait until a response is received to continue to the next form action. If you check the box labeled "Wait for the webhook response before continuing actions," the form submission process will wait for a webhook response before continuing and return the results to the front end in the submission's metadata field. Any errors received from webhooks whose responses are being awaited will stop the form submission process and be displayed to the form user.
External Id Type and Path
If the webhook endpoint creates a data object in the external system, there is often an id created and returned in the response. If you want to save this id and associate it with the submission in Form.io, you can specify a type and id path here. The External Id Type is the reference key of the external service's database (e.g. "github"). The External Id Path is the path to the id field in the external service's response object. For example, in the response below (returned from AirTable), the path would read records[0].id. If you use the same External Id Type in multiple webhooks, any subsequent changes to the id field will be updated in the Form.io submission data.
Retry Request
If the webhook fails the first time, it is possible to retry the request. To use a retry request, you need to set the type of repeat, the maximum number of attempts, and the initial delay in milliseconds.
Retry Type: If the initial request fails, the calculation of the delay between further attempts will be calculated based on the type of repeat.
Constant - the delay between attempts is constant and equal to the initial delay (e.g., 200ms, 200ms, 200ms, etc.)
Linear - the delay between attempts increases linearly (e.g., 100ms, 200ms, 300ms, etc.)
Exponential - the delay between attempts increases exponentially (e.g., 100ms, 200ms, 400ms, 800ms, etc.)
Jitter - mitigate correlations and improve the performance by adding randomness (e.g., 170ms, 275ms, 196ms, 511ms, etc.)
Exponentially Jitter - mitigate any corrections, fewer spikes, and a smoother distribution than Jitter type (e.g., 196ms, 267ms, 595ms, 1132ms, etc.)
Number of attempts: The maximum number of additional request attempts if the request fails. If the request is successful, the retry request is stopped.
Initial Delay: The initial delay between the initial request and the first additional attempt. The delay is calculated based on the retry type.
Webhook Testing
In order to ease development and testing around your webhooks, we've created an example application called Webhook Receiver. You can install this application on your local machine by executing the following commands in your terminal.
This will run the receiver on your local machine. To easily connect services running on your local computer to the wider internet, we recommend using a tool (often called a "tunneler") such as ngrok. Once you have a ngrok account and the software installed, you will need to expose the Webhook Receiver application running on your local machine by running the following command in your terminal:
You should now see the tunnel address that's been created:
This indicates that the address http://941a7c65.ngrok.io will tunnel to the Webhook Receiver application running on your local machine. Once the tunnel is running, configure a Webhook Action on your form with the following settings:
Webhook URL: http://941a7c65.ngrok.io
Authorize User: test
Authorize Password: password123
(The username and password can be changed in the config.json file of in the Webhook Reciever's root directory.)
You can now submit the form and see the data come through your local machine!
Sample Payload
Here's a sample of what the default request payload looks like on a form that has a text field named "textField" and a number field named "number":
Last updated
Was this helpful?