> ## Documentation Index
> Fetch the complete documentation index at: https://help.reevo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Any Form with a Custom Webhook

> Send submissions from any form builder or app that can POST JSON or form fields to a webhook, then map the incoming keys to your CRM.

Use the **Custom webhook** option when your form provider is not listed in Reevo but can send submissions to a webhook URL. Reevo receives each submission, turns its keys into source fields that you map to your CRM, and runs the connected workflow.

***

## Before you start

You need a form or app that can send an HTTP `POST` request to a webhook URL, and an external form created in Reevo with **Custom webhook** selected as the provider. Follow [Connecting an External Form to Reevo](/Prospecting-and-Outreach/Connecting-an-External-Form#create-the-external-form-in-reevo) to create it and copy its webhook URL.

<Info>
  If your provider has its own option in Reevo, such as Webflow, Typeform, or HubSpot, use that option instead. Dedicated providers understand that provider's payload format.
</Info>

***

## Send submissions to the webhook URL

1. In your form provider or app, open its webhook or integration settings.
2. Add a new webhook and paste the webhook URL you copied from Reevo.
3. Set the method to `POST`.
4. Send the submission as JSON (`application/json`) or as form fields (`application/x-www-form-urlencoded` or `multipart/form-data`).
5. Save the webhook.

A simple JSON body looks like this:

```json theme={null}
{
  "email": "jane@example.com",
  "first_name": "Jane",
  "company": "Example Inc",
  "utm_source": "newsletter"
}
```

***

## Understand the incoming fields

Reevo uses each key in the request body as a source field. The field name you see in Reevo is the key exactly as it was sent.

| Payload shape | How Reevo reads it |
| :- | :- |
| **Top-level key**, such as `"email": "jane@example.com"` | Source field `email` |
| **Nested object**, such as `"contact": { "city": "Austin" }` | Source field `contact.city`. Reevo reads up to three levels deep, such as `contact.address.city`, and ignores anything deeper. |
| **List of plain values**, such as `"interests": ["CRM", "Email"]` | Source field `interests` with multiple values |
| **List of objects**, such as an array of question and answer objects | Ignored |
| **Empty value** (`null`) | Ignored |
| **True or false value** | Received as the text `true` or `false` |
| **Number** | Received as text, such as `42` |

<Tip>
  Send a flat body with clear, unique key names. If two keys resolve to the same source field name, Reevo keeps the first one in the payload.
</Tip>

<Note>
  If your provider sends answers as a list of objects, Reevo cannot read those answers with the Custom webhook option. Reshape the payload into simple key and value pairs before it is sent, or ask Reevo support whether a dedicated provider is available.
</Note>

***

## Map and test the form in Reevo

1. Send a test submission from your form or app using recognizable test values.
2. Return to the external form builder in Reevo and click **Populate from submission**.
3. Select the test submission.
4. Map each incoming key to its Contact or Account field.
5. Configure the connected workflow, then click **Launch**.
6. Send another submission and confirm the submission and workflow appear in Reevo.

<Info>
  For the complete mapping and workflow steps, see [Connecting an External Form to Reevo](/Prospecting-and-Outreach/Connecting-an-External-Form#map-incoming-fields-to-your-crm).
</Info>

***

## Track UTM parameters

Reevo can record the campaign that drove each submission. Send UTM values as keys in the request body, then mark those fields as UTM parameters in Reevo.

### 1. Send UTM keys with the exact standard names

Add any of the five standard UTM keys to the request body:

```json theme={null}
{
  "email": "jane@example.com",
  "first_name": "Jane",
  "utm_source": "newsletter",
  "utm_medium": "email",
  "utm_campaign": "spring_launch",
  "utm_term": "crm software",
  "utm_content": "header_cta"
}
```

Reevo only recognizes these exact key names, in lowercase and at the top level of the body: `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, and `utm_content`.

<Warning>
  Keys such as `UTM_Source`, `utmSource`, `source`, or a nested object such as `"utm": { "source": "newsletter" }` are not recorded as UTM parameters. Rename them to the standard keys in your provider before the submission is sent.
</Warning>

<Tip>
  Most form tools can capture UTM values from the page URL into hidden fields. Name those hidden fields with the standard keys so they arrive in the body as `utm_source`, `utm_medium`, and so on.
</Tip>

### 2. Mark the fields as UTM parameters in Reevo

1. Send a test submission that includes the UTM keys.
2. In the external form builder, click **Populate from submission** and select the test submission.
3. For each UTM source field, open the mapping dropdown and choose the matching option under **UTM params**. Fields named `utm_source`, `utm_medium`, and so on are usually recognized automatically.
4. Click **Launch** or **Launch changes**.

<Info>
  A field marked as a UTM parameter is recorded on the submission. It is not written to a Contact or Account field. Choosing a UTM option also locks the source field name to the standard UTM key, so the key in your request body must use that exact name.
</Info>

### 3. Check the results

* Open a submission from the **Submissions** tab to see its values under **UTM parameters**.
* Open the form's **Insights** tab to see submissions grouped by UTM source and campaign in the **Channel breakdown**.

UTM values are recorded for submissions received after the form is launched with the UTM fields. Earlier submissions are not updated.

***

## Troubleshooting Custom webhook

* **No submission appears in Reevo**: confirm that your provider sends a `POST` request and that the webhook URL exactly matches the URL from Reevo.
* **A field is missing**: check that the key is in the request body with a value, is no more than three levels deep, and is not inside a list of objects. Then send another test submission and populate the payload schema again.
* **A mapping stops working after changing the payload**: check whether the key name changed, then remap the updated source field.
* **UTM values are missing from a submission**: confirm that the request body uses the exact lowercase keys, such as `utm_source`, at the top level, that each UTM field is marked under **UTM params**, and that you launched the form after adding them.
* **Submissions from another form appear**: Reevo accepts every submission sent to this webhook URL. Use a separate external form and webhook URL for each source form.

> Still have questions? [Sign in](https://app.reevo.ai) and use Ask Reevo for help or to raise a support ticket.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.