> ## Documentation Index
> Fetch the complete documentation index at: https://www.vollna.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# n8n Integration

> Send job alerts, proposals and invitations from Vollna to n8n workflows

Vollna sends two kinds of webhooks to [n8n](https://n8n.io), cloud or self-hosted. Set up the one you need, or both.

| What n8n receives | Where you set it up in Vollna | One request carries |
| - | - | - |
| [Job alerts](#job-alerts) | **Notifications → Add notification → Webhook** | New jobs from your filters, in a `projects` array |
| [Proposals and invitations](#proposals-and-invitations) | **Settings → Developers → Webhooks** | One proposal or invitation event |

The two payloads differ, so give each one its own workflow with its own Webhook node.

> [!NOTE]
>
> Webhooks are available on [higher plans](https://www.vollna.com/pricing) or as a paid add-on.

> [!WARNING]
>
> Self-hosted n8n must be reachable from the public internet over HTTPS. Vollna can't deliver to `localhost` or private network addresses.

Every Webhook node has two URLs. The **Test URL** works only while the editor listens for a test event. The **Production URL** works once the workflow is published (the **Active** toggle on n8n 1.x). Vollna must end up on the Production URL.

n8n puts the JSON payload under `body`, so fields read as `body.projects`, `body.data` and so on.

## Job alerts

### Step 1: Create a Webhook node

1. Create a new workflow and add a **Webhook** node as the trigger.
2. Set **HTTP Method** to `POST`.
3. Click **Listen for test event** and copy the **Test URL**.

### Step 2: Send a test from Vollna

1. Go to **Dashboard → Notifications** and click **Add notification**.
2. Pick **Webhook** and paste the Test URL into **URL**.
3. Pick the filters that should send jobs.
4. Click **Send test**. Vollna sends up to 3 recent jobs from those filters, and n8n shows them in the Webhook node.

Keep the dialog open for the next step.

### Step 3: Switch to the Production URL

1. In n8n, copy the node's **Production URL** and publish the workflow.
2. In Vollna, replace the URL with the Production URL and click **Add notification**.

### Step 4: Run each job through the workflow

One request can carry several new jobs. To handle each job as its own item:

1. Add a **Split Out** node after the Webhook node.
2. Set **Field to Split Out** to `body.projects`.
3. Connect the nodes that should run once per job.

For example, **Webhook → Split Out → IF (`client_details.total_spent` > 10000) → Slack** posts jobs from clients who have spent more than \$10,000 on Upwork, and the IF node drops the rest.

The [job alert field reference](https://www.vollna.com/docs/notifications/webhooks.md#field-reference) lists every field.

## Proposals and invitations

### Step 1: Create a second workflow

1. Create a new workflow with a **Webhook** node, set to `POST`.
2. Click **Listen for test event** and copy the **Test URL**.

### Step 2: Send a test from Vollna

1. Go to **Dashboard → Settings → Developers → Webhooks** and click **Add Endpoint**.
2. Paste the Test URL into **Webhook URL**.
3. Under **Events to receive**, tick the events you need. **Proposal Status Changed** also lets you pick which statuses send an event.
4. Click **Send Test Request**. Vollna sends your newest proposal, or your newest invitation if you picked only invitation events, and n8n shows it in the Webhook node.

### Step 3: Switch to the Production URL

1. In n8n, copy the node's **Production URL** and publish the workflow.
2. In Vollna, replace the URL with the Production URL and click **Create Webhook**.

### Step 4: Map the event

Map `body.event`, `body.timestamp` and the fields under `body.data`, such as `body.data.jobDetails.title` and `body.data.isViewed`. The test request has the event `webhook.test`, so an IF node on `body.event` can drop it.

One request carries one event, so this workflow needs no Split Out.

The [Team Webhooks payload](https://www.vollna.com/docs/integrations/webhooks.md#payload-format) shows every field. To trace repeated deliveries, log `X-Vollna-Event-Id` (the same value as `body.id`). To process each proposal once, key on `body.data.applicationUid`.

## Troubleshooting

1. **The test works but live events don't arrive.** Publish the workflow and point Vollna at the **Production URL**. The Test URL works only while the editor listens.
2. **n8n answers 404.** The path differs between the Test URL and the Production URL. Copy the exact URL from the Webhook node again.
3. **Fields come back empty.** Read them under `body`, for example `body.filter.name` or `body.data.jobDetails.title`.
4. **The proposal test shows only `test`, `message` and `webhook_url` under `body.data`.** You have no proposals or invitations in Vollna yet, so the test carries a test message. Send the test again after your first proposal syncs.


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