# Webhook Actions

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.

{% hint style="info" %}
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.
{% endhint %}

<figure><img src="https://501951130-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6LdEf8SjBIeQDsRL3BdV%2Fuploads%2FqeYvMBRehyoKKD5CTto2%2Fimage.png?alt=media&#x26;token=3a870f0c-fbb9-444d-9314-bd9fbace5a4c" alt=""><figcaption></figcaption></figure>

## 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:

```
{
  request: request, // an object containing request body to the form.io server.
  submission: submission, // an object containing the submission object from the request.
  params: params, // an object containing the params for the request such as query parameters or url parameters.
}
```

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.

```
{
	“records”: [
		{
			“id”: “recZ37x123HWzDLaJ”,
			“createdTime”: “2022-09-24T01:31:25.000Z”,
			“fields”: {
				“Customer”: “Joe Smith”
			}
		}
	]
}
```

**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.&#x20;

**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.&#x20;

## Webhook Testing

In order to ease development and testing around your webhooks, we've created an example application called [**Webhook Receiver**](https://github.com/formio/formio-webhook-receiver). You can install this application on your local machine by executing the following commands in your terminal.

```
npm install
node index.js
```

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**](https://ngrok.com/). Once you have a ngrok account and the software [**installed**](https://ngrok.com/download), you will need to expose the Webhook Receiver application running on your local machine by running the following command in your terminal:

```
ngrok http 4001
```

You should now see the tunnel address that's been created:

```
Version                       2.1.14
Region                        United States (us)
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://941a7c65.ngrok.io -> localhost:4001
Forwarding                    https://941a7c65.ngrok.io -> localhost:4001
```

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":

```
{
  request: {
    data: { textField: 'Test value', number: 12345, submit: true },
    owner: '61c5e59add38c4e4a356acb0',
    access: [],
    metadata: {
      timezone: 'America/Chicago',
      offset: -300,
      origin: 'https://portal.form.io',
      referrer: '',
      browserName: 'Netscape',
      userAgent: '<user agent value>',
      pathName: '/',
      onLine: true,
      headers: [Object]
    },
    state: 'submitted',
    form: '62a745944e836ccf1c0ba167',
    project: '61d21695ecb3f85c774e8f09',
    _fvid: 0
  },
  submission: {
    owner: '61c5e59add38c4e4a356acb0',
    deleted: null,
    roles: [],
    _id: '62e052a316f1ad4f786d4038',
    _vid: 0,
    _fvid: 0,
    state: 'submitted',
    data: { textField: 'Test value', number: 12345, submit: true },
    access: [],
    metadata: {
      timezone: 'America/Chicago',
      offset: -300,
      origin: 'https://portal.form.io',
      referrer: '',
      browserName: 'Netscape',
      userAgent: '<user agen value>',
      pathName: '/',
      onLine: true,
      headers: [Object]
    },
    form: '62a745944e836ccf1c0ba167',
    project: '61d21695ecb3f85c774e8f09',
    externalIds: [],
    externalTokens: [],
    created: '2022-07-26T20:46:27.232Z',
    modified: '2022-07-26T20:46:27.233Z',
    __v: 0
  },
  params: { formId: '62a745944e836ccf1c0ba167' }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.form.io/form-building/actions/webhook-actions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.