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

# Team Webhooks (Proposals & Invitations)

> Receive real-time webhook events when proposals or invitations change in your workspace

Team Webhooks let your system receive **real-time HTTP requests** when key events happen in Vollna (proposal created, proposal status/view state changed, invitation created, invitation status changed).

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

> [!TIP]
>
> To send proposals and invitations to a no-code tool, follow the guide for [Zapier](https://www.vollna.com/docs/integrations/zapier.md#proposals-and-invitations), [Make](https://www.vollna.com/docs/integrations/make.md#proposals-and-invitations) or [n8n](https://www.vollna.com/docs/integrations/n8n.md#proposals-and-invitations). For new jobs from your filters, use [Webhook Notifications](https://www.vollna.com/docs/notifications/webhooks.md) instead.

## Where to configure

* Go to **Dashboard → Settings → Developers → Webhooks** (or use the **Webhooks & API** shortcut in the top-right user menu).
* Click **Add Endpoint**.

## Step 1: Set your endpoint URL

* Enter the **Webhook URL** (a public HTTPS endpoint that accepts `POST`).

![Webhook creation form with endpoint URL field](https://mintcdn.com/acme-d4aec364/eMtz9nsODY2vod_s/images/create-webhook-vollna-dashboard.png?fit=max\&auto=format\&n=eMtz9nsODY2vod_s\&q=85\&s=218f9ba68672f704f81cd5611eb98516)

## Step 2: Pick events to receive

You can subscribe to one or more events:

* **Proposal Created** (`upwork_proposal.created`): triggered when a new proposal is saved in your workspace.
* **Proposal Status Changed** (`upwork_proposal.status_changed`): triggered when the proposal’s state changes. This includes **view state** changes (e.g. when `isViewed` toggles), and also changes to `isInterviewed`, `isHired`, `isWithdrawn`, `isArchived`.
* **Invitation Created** (`upwork_invitation.created`): triggered when a new invitation is saved in your workspace.
* **Invitation Status Changed** (`upwork_invitation.status_changed`): triggered when an invitation’s `status` or `reason` changes.

## Step 3 (optional): Configure authentication

If your endpoint requires auth, Vollna can send:

* **Bearer Token**: `Authorization: Bearer <token>`
* **Basic Auth**: `Authorization: Basic base64(username:password)`
* **Custom Header**: any header name and value you configure (e.g. `X-Api-Key: <value>`)

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

## Technical Specifications

Understanding the technical details of how Vollna sends webhook requests:

* **HTTP Method**: POST
* **Content-Type**: application/json
* **Timeout**: 10 seconds
* **User-Agent**: `Vollna-Webhooks/1.0`
* **`X-Vollna-Event-Id`** header: every request carries the same `evt_*` identifier as the `id` field in the JSON body — useful for logging, deduping, and tracing without parsing the body.

### Testing Your Webhook

Click **Send Test Request** in the webhook form to check that your endpoint is reachable and accepts your auth settings. The test request has the event `webhook.test`, and its `data` is your newest proposal in the same shape as a live event. If you picked only invitation events, it is your newest invitation. With no proposals or invitations yet, `data` holds a test message.

## Payload format

Every request is JSON with the same top-level structure:

* `id`: unique delivery identifier prefixed with `evt_` (e.g. `evt_a4f1c0d3e8b9...`). One id per delivery — log it so you can trace any request back to the matching row under **Logs**.
* `event`: the event name (e.g. `upwork_proposal.status_changed`)
* `timestamp`: ISO-8601 timestamp
* `data`: the full proposal or invitation, in the same shape as the [Proposals API](https://www.vollna.com/docs/api-reference/proposals/list-proposals.md) and [Invitations API](https://www.vollna.com/docs/api-reference/invitations/list-invitations.md) return it, including the nested `project` object

> [!NOTE]
>
> The `id` is a public, opaque token. It does not encode any internal database id and is safe to log, store, and forward. The same value is sent in the `X-Vollna-Event-Id` HTTP header.

### Example: proposal status/view state changed

The nested `project` object is shortened here — it carries every field of the [Project schema](https://www.vollna.com/docs/api-reference/projects/get-project-by-lookup.md).

```json theme={null}
{
  "id": "evt_a4f1c0d3e8b9d4f6a1c2",
  "event": "upwork_proposal.status_changed",
  "timestamp": "2026-05-16T12:34:56+00:00",
  "data": {
    "applicationUid": "1234567890123456",
    "submittedAt": "2026-05-16T12:20:11+00:00",
    "coverLetter": "Hi, I have built exactly this kind of integration...",
    "answers": [
      { "question": "How many years of PHP experience do you have?", "answer": "8 years" }
    ],
    "jobDetails": {
      "title": "S3 Bucket to Bigcommerce API",
      "postedAt": "2026-05-16T11:58:03+00:00",
      "url": "https://www.upwork.com/jobs/~01146ebeb34b098d8c"
    },
    "freelancer": { "id": 42, "fullName": "John Doe", "imagePath": null },
    "businessManager": null,
    "upworkProfile": { "id": 7, "label": "ACME, Inc.", "type": "agency" },
    "upworkOrganization": { "id": 7, "label": "ACME, Inc.", "type": "agency" },
    "connects": 16,
    "boost": 0,
    "terms": { "hourlyRate": 45 },
    "isViewed": true,
    "isInterviewed": false,
    "isHired": false,
    "isWithdrawn": false,
    "isInvitation": false,
    "isArchived": false,
    "occupationUid": "1110580755057594368",
    "occupationTitle": "Full Stack Development",
    "submissionPosition": 3,
    "boostOutbid": false,
    "coverLetterVariant": null,
    "responseTimeMinutes": 22,
    "attachments": [],
    "biddingTemplate": { "id": 12, "name": "Default template" },
    "project": {
      "title": "S3 Bucket to Bigcommerce API",
      "url": "https://www.upwork.com/jobs/~01146ebeb34b098d8c",
      "publishedAt": "2026-05-16T11:58:03+00:00",
      "skills": ["PHP", "API Integration", "Amazon S3"],
      "budget": { "type": "Hourly rate", "amount": "$15 - $25" },
      "clientDetails": { "paymentMethodVerified": true, "country": "United States", "totalSpent": "103.5k" }
    }
  }
}
```

## Debugging delivery

Open **Dashboard → Settings → Developers → Webhooks → Logs** to inspect every delivery attempt. Each row shows the timestamp (in your timezone, with full UTC + milliseconds on hover), the `evt_*` Message ID, event type, and status. Click a row to view the request payload, response body, and any error message.

The **Activity** tab shows hourly delivery counts (Successful / Failed) over the last 6 hours so you can spot incidents at a glance.

## Best practices

* **Return 2xx quickly** (ideally \< 5s). Do heavy work asynchronously.
* **Log the `id`** on receipt — pair it with your own internal handler trace so you can correlate problems with the **Logs** tab in Vollna.
* **Make handlers idempotent** based on the business id inside `data` (e.g. `applicationUid`) — your handler may run more than once for the same underlying record if you re-process or replay traffic.
* **Validate JSON** and tolerate missing/optional fields in `data`.

## Troubleshooting

### Common Issues

#### Webhook Not Receiving Requests

1. **Check webhook URL**: Ensure it's publicly accessible and returns a 2xx status code
2. **Verify authentication**: If using auth, check credentials are correct
3. **Test connectivity**: Use the "Send test notification" button in the setup form
4. **Check firewall**: Ensure your server allows incoming requests from Vollna

#### Missing Fields in Webhook Data

* The `data` object is a serialized entity and fields may be optional depending on the record.
* Always check if a field exists before accessing it.

### Testing Your Integration

1. **Use test notification**: Click "Send Test Request" in the webhook setup
2. **Check logs**: Monitor your server logs for incoming requests
3. **Validate JSON**: Ensure your endpoint can parse the JSON payload
4. **Test authentication**: Verify auth headers are received correctly
5. **Response handling**: Ensure you return appropriate HTTP status codes


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