Skip to main content
Webhooks allow you to receive notifications from Vollna in real-time.
Webhooks are available with Agency plan or as paid add-on.

​
Step 1: Access Notification Settings

  1. Go to Dashboard in the main navigation menu > Notifications.
  2. Locate Webhook from the list of available integrations.

​
Step 2: Configure Webhook

  1. Click on Setup next to Webhook.
  2. Enter your webhook URL in the form.
  3. If needed, you can setup authentication for your webhook.
  4. Review other settings and click on Save settings button.
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
  • Retry Logic: Automatic retry on failure
  • Auto-disable: Webhooks are automatically disabled after 24 hours of consecutive failures

​
Testing Your Webhook

You can test your webhook configuration by clicking the “Send test notification” button in the notification setup form. This will send a sample notification to verify your endpoint is working correctly.

​
Receive Notifications

After you’ve set up your webhook, you will start receiving notifications as soon as new job opportunities are published.
Request Body Example
{
    "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",
            "site": "Upwork.com",
            "published": "2024-08-24T07:16:32+00:00",
            "us_only": true,
            "uk_only": false,
            "duration": "Less than 1 month",
            "engagement": "Less than 30 hrs/week",
            "experience_level": "Intermediate",
            "job_type": "One-time project",
            "categories": ["Web Development", "API Development"],
            "questions": [
                "What experience do you have with Bigcommerce API integrations?",
                "Have you previously worked with Amazon S3 for product imports?",
                "What is your estimated timeline for completing this integration?"
            ],
            "preferred_qualifications": {
                "freelancer_type": "Individual",
                "project_length": "1 to 3 months",
                "expertise_level": "Expert"
            },
            "filters": [
                {
                    "id": 123,
                    "name": "Backend Development",
                    "url": "https://www.vollna.com/dashboard/filter/123"
                }
            ],
            "client_details": {
                "rank": "Excellent",
                "payment_method_verified": true,
                "total_spent": 82639.95,
                "total_hires": 25,
                "jobs_active": 3,
                "avg_hourly_rate_paid": 25.002608695652,
                "total_hours_paid": 1500,
                "rating": 4.95,
                "reviews": 13,
                "registered_at": "2020-05-17T00:00:00+00:00",
                "country": {
                    "name": "United States",
                    "iso_code2": "US"
                }
            }
        }
    ]
}

​
Error Handling & Reliability

​
Automatic Retry Logic

  • Failed webhook requests are automatically retried
  • Vollna implements exponential backoff for retries
  • Maximum retry attempts ensure your system isn’t overwhelmed

​
Webhook Health Monitoring

  • Vollna tracks the success/failure rate of your webhook
  • Webhooks are automatically disabled if:
    • 10 consecutive failures occur (regardless of time)
    • 3+ failures within 24 hours AND no successful notifications in the last 24 hours
  • You can re-enable webhooks once the issue is resolved

​
Failure Scenarios

Common reasons for webhook failures:
  • HTTP 4xx errors: Client errors (400 Bad Request, 401 Unauthorized, 404 Not Found, etc.)
  • HTTP 5xx errors: Server errors (500 Internal Server Error, 502 Bad Gateway, etc.)
  • Timeout: Endpoint takes longer than 10 seconds to respond
  • Connection failures: Server unreachable, DNS resolution issues, network problems
  • SSL/TLS issues: Certificate problems (though self-signed certificates are supported)
Vollna considers any HTTP status code 400 or above as a failure and will retry the request.

​
Best Practices

  • Respond quickly: Aim to respond within 5 seconds
  • Return appropriate status codes: Use 2xx for success, 4xx/5xx for errors
  • Monitor your endpoint: Set up monitoring to catch issues early

​
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

​
Webhook Disabled Automatically

  • This happens after 10 consecutive failures, or 3+ failures with no success in 24 hours
  • Check your server logs for specific error messages
  • Common causes: 404 Not Found, 500 Server Error, timeouts, connection issues
  • Verify your endpoint returns HTTP 2xx status codes for successful requests
  • Re-enable the webhook after fixing the issue

​
Missing Fields in Webhook Data

  • Some fields may be optional and not present for all projects
  • Always check if a field exists before accessing it
  • Refer to the complete schema above for all possible fields

​
SSL/TLS Certificate Issues

  • Vollna supports self-signed certificates
  • Ensure your webhook endpoint uses HTTPS for production
  • Check certificate validity and expiration

​
Testing Your Integration

  1. Use test notification: Click “Send test notification” 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

​
Getting Help

If you’re still experiencing issues:
  • Check the webhook health status in your notification settings
  • Review your server error logs
  • Contact Vollna support with your webhook configuration details
  • Include any error messages from your webhook endpoint logs