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

# Webhook Notifications (New Jobs)

> Send webhook notifications when new job opportunities match your filters

Webhook Notifications allow you to receive **real-time job alerts** when new projects are published and match your selected filters.

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

> [!TIP]
>
> To send job alerts to a no-code tool, follow the guide for [Zapier](https://www.vollna.com/docs/integrations/zapier.md), [Make](https://www.vollna.com/docs/integrations/make.md) or [n8n](https://www.vollna.com/docs/integrations/n8n.md). Any other tool that gives you a webhook URL, such as Pipedream or Activepieces, works the same way.

## Step 1: Add the notification

1. Go to **Dashboard → Notifications** and click **Add notification**.
2. Pick **Webhook**.

## Step 2: Configure your webhook

1. Paste your endpoint into **URL**.
2. If your endpoint needs auth, pick **Basic auth** or **Bearer token** under **Authentication**.
3. Pick the filters that should send jobs.
4. Click **Add notification**.

> [!WARNING]
>
> Authentication credentials are stored securely and are not shared with any third parties.

## Technical Specifications

* **HTTP Method**: POST
* **Content-Type**: application/json
* **Timeout**: 10 seconds
* **Batching**: one request carries every new job of one alert, in the `projects` array

### Testing your webhook

Click **Send test** in the setup form. Vollna sends up to 3 recent jobs from the picked filters, in the same format as a live alert.

## Payload example

After you’ve set up your webhook, you will start receiving notifications when new job opportunities match your selected filters.

```json theme={null}
{
  "total": 19,
  "results_url": "https://www.vollna.com/dashboard/monitoring/result/12345",
  "filter": {
    "id": 123,
    "name": "Backend Development",
    "url": "https://www.vollna.com/dashboard/filter/123"
  },
  "filters": [
    {
      "id": 123,
      "name": "Backend Development",
      "url": "https://www.vollna.com/dashboard/filter/123"
    },
    {
      "id": 124,
      "name": "API Development",
      "url": "https://www.vollna.com/dashboard/filter/124"
    }
  ],
  "projects": [
    {
      "url": "https://www.vollna.com/go?module=webhook&uid=0&tid=0&pid=3359&url=https%253A%2F%2Fwww.upwork.com%2Fjobs%2F%257E01146ebeb34b098d8c",
      "title": "S3 Bucket to Bigcommerce API",
      "description": "I am looking for a developer who can create an API intergration to import products from an Amazon S3 bucket to Bigcommerce...",
      "skills": "PHP, API Integration, Amazon S3, BigCommerce",
      "budget_type": "hourly",
      "budget": "15 - 25 USD",
      "budget_raw": { "type": "hourly", "fixedAmount": null, "hourlyMin": 15, "hourlyMax": 25 },
      "site": "Upwork.com",
      "published": "2024-08-24T07:16:32+00:00",
      "us_only": false,
      "uk_only": false,
      "duration": "1 to 3 months",
      "engagement": "Less than 30 hrs/week",
      "experience_level": "Intermediate",
      "job_type": "Hourly",
      "categories": ["Web Development"],
      "questions": [],
      "preferred_qualifications": null,
      "connects_price": 16,
      "job_attachments_count": 0,
      "is_featured": false,
      "is_upwork_enterprise_client": false,
      "client_details": {
        "rank": null,
        "payment_method_verified": true,
        "phone_verified": true,
        "total_spent": 12500,
        "total_hires": 24,
        "hire_rate": 0.72,
        "jobs_posted": 31,
        "jobs_open": 2,
        "jobs_active": 3,
        "avg_hourly_rate_paid": 32.5,
        "total_hours_paid": 1840,
        "rating": 4.9,
        "reviews": 18,
        "registered_at": "2019-03-12T10:00:00+00:00",
        "country": {
          "name": "United States",
          "iso_code2": "US"
        },
        "city": "Austin",
        "country_timezone": "America/Chicago (UTC-05:00)",
        "industry": "Tech & IT",
        "company_size": "10"
      }
    }
  ]
}
```

### Field reference

Top-level fields:

| Field | Type | Description |
| - | - | - |
| `total` | number | Number of new jobs in this delivery. |
| `results_url` | string | Link to the result page in your Vollna dashboard. |
| `filter` | object | The filter that produced this delivery (`id`, `name`, `url`). |
| `filters` | object\[] | All filters attached to the notification (`id`, `name`, `url`). Only present when there are several. |

Fields of each item in `projects[]`:

| Field | Type | Description |
| - | - | - |
| `url` | string | Tracked link to the job posting. |
| `title` | string | Job title. |
| `description` | string | Job description. |
| `skills` | string or null | Required skills as one comma-separated string. |
| `budget_type` | string | `hourly`, `fixed`, or `no` — `no` means the posting doesn't specify a budget. |
| `budget` | string | Hourly rate range or fixed price range. |
| `budget_raw` | object | The same budget as numbers: `type` (`hourly`, `fixed`, `no`), `fixedAmount`, `hourlyMin`, `hourlyMax`. Unused fields are `null`. |
| `site` | string | Source marketplace (e.g. `Upwork.com`). |
| `published` | string | ISO-8601 publish timestamp. |
| `us_only` | boolean | Job restricted to US freelancers. |
| `uk_only` | boolean | Job restricted to UK freelancers. |
| `duration` | string | Project length label. |
| `engagement` | string | Weekly workload label. |
| `experience_level` | string | Required experience level. |
| `job_type` | string | Job type label. |
| `categories` | string\[] | Marketplace categories. |
| `questions` | string\[] or null | Screening questions from the client. |
| `preferred_qualifications` | object or null | Client's preferred qualifications, when provided (snake\_case keys). |
| `connects_price` | number or null | Connects required to apply (Upwork). |
| `job_attachments_count` | number | Number of files attached to the job posting. |
| `is_featured` | boolean | Whether the job is a featured (boosted) posting. |
| `is_upwork_enterprise_client` | boolean | Whether the client is an Upwork Enterprise client. |
| `client_details` | object | Client stats — see below. |
| `client_work_history` | object\[] | Client's recent work history. Only present when available. Each item has `job_info` (`uid`, `title`, `type`, `url`), `status`, `start_date`, `end_date`, `total_hours`, `total_charge`, `contractor_name`, and, when present, `feedback`, `feedback_to_client` and `rate`. |
| `filters` | object\[] | Which of the notification's filters matched this job (`id`, `name`, `url`). Only present with multiple filters. |

Fields of `client_details`:

| Field | Type | Description |
| - | - | - |
| `rank` | string or null | Client rank level. |
| `payment_method_verified` | boolean | Whether the client's payment method is verified. |
| `phone_verified` | boolean or null | Whether the client's phone number is verified. |
| `total_spent` | number | Total amount the client has spent. |
| `total_hires` | number | Total number of hires. |
| `hire_rate` | number or null | Client hire rate as a fraction between 0 and 1 (e.g. `0.72` = 72%). |
| `jobs_posted` | number or null | Total jobs the client has posted. |
| `jobs_open` | number or null | Jobs the client currently has open. |
| `jobs_active` | number or null | Client's active contracts. |
| `avg_hourly_rate_paid` | number | Average hourly rate the client has paid. |
| `total_hours_paid` | number or null | Total hours the client has paid for. |
| `rating` | number | Client rating. |
| `reviews` | number | Number of reviews. |
| `registered_at` | string or null | ISO-8601 registration date. |
| `country` | object or null | Client country (`name`, `iso_code2`). |
| `city` | string or null | Client city, when the marketplace provides it. |
| `country_timezone` | string or null | Client timezone as reported by the marketplace (e.g. `Europe/London (UTC+01:00)`). |
| `industry` | string or null | Client industry, when provided. |
| `company_size` | string or null | Client company size (number of employees), when provided. |

## Best practices

* **Respond quickly** (aim \< 5 seconds) and do processing asynchronously.
* **Return 2xx** for successful deliveries.
* **Validate fields defensively**: projects and client fields may vary by site and job type.

## Troubleshooting

### Webhook not receiving requests

1. Ensure your URL is publicly reachable and responds with HTTP 2xx.
2. Verify auth settings (token/credentials).
3. Use **Send test request** to validate connectivity.
4. Check server/firewall logs for blocked requests.


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