Skip to main content
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).
Team Webhooks are available with Agency plan or as paid add-on.

​
Where to configure

  • Go to Dashboard → Top-right corder → Webhooks
  • Click Create webhook.

​
Step 1: Set your endpoint URL

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

​
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)
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

​
Testing Your Webhook

You can test your webhook configuration by clicking Send Test Request in the webhook form. This sends a sample request to verify your endpoint is reachable and accepts your auth settings.

​
Payload format

Every request is JSON with the same top-level structure:
  • event: the event name (e.g. upwork_proposal.status_changed)
  • timestamp: ISO-8601 timestamp
  • data: the proposal or invitation payload (serialized)

​
Example: proposal status/view state changed

{
  "event": "upwork_proposal.status_changed",
  "timestamp": "2025-12-16T12:34:56+00:00",
  "data": {
    "id": 12345,
    "application_uid": "1234567890123456",
    "isViewed": true,
    "isInterviewed": false,
    "isHired": false,
    "isWithdrawn": false,
    "isArchived": false
  }
}

​
Debugging delivery

Open Dashboard → Integrations → Webhooks and check Recent Requests. You can inspect:
  • delivery status + HTTP status code
  • request payload
  • response body / error message

​
Best practices

  • Return 2xx quickly (ideally < 5s). Do heavy work asynchronously.
  • Make handlers idempotent (you may receive the same event more than once).
  • 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