Webhooks
Real-time job notifications delivered to your endpoints
Quick Start
1
Configure Feed
Select which job feeds trigger notifications
2
Create Webhook
Set up your webhook endpoint in the dashboard
3
Receive Alerts
Get real-time job notifications at your endpoint
Premium Feature: Webhooks are available with active subscriptions.
How Webhooks Work
When new jobs are posted on Upwork that match your configured feeds, Winfast automatically:
- Processes the job against your feed criteria
- Queues webhook notifications for matching jobs
- Sends HTTP POST requests to your configured endpoints
- Logs delivery status and manages retries
- Failed attempts remain for automatic retries
- Maximum 10 retry attempts before disabling webhook
Webhook Payload
Each webhook delivers a JSON payload with comprehensive job information:
{
"event": "job.matched",
"webhook_id": "webhook_123456",
"timestamp": "2024-01-15T10:30:00Z",
"feed": {
"id": "feed_789",
"name": "React Developer Jobs"
},
"data": {
"job": {
"idx": 1,
"client_active_assignments": 68,
"client_avg_hourly_jobs_rate": "15.662137248512389",
"client_city": "Las Vegas",
"client_country": "United States",
"client_country_timezone": "America/Managua (UTC-06:00)",
"client_feedback_count": 1576,
"client_hired_in_past": 0,
"client_hours_count": "2240.17",
"client_is_enterprise": false,
"client_open_jobs": 4,
"client_payment_method_is_verified": true,
"client_posted_jobs": 67,
"client_rating": "5",
"client_total_assignments": 2365,
"client_total_charges": "115430.33",
"client_total_jobs_with_hires": 93,
"job_category": "editing-proofreading-services",
"job_category_group": "writing",
"job_category_group_label": "Writing",
"job_client_activity_invitations_sent": 20,
"job_client_activity_last_buyer_activity": "2025-10-01T14:20:14.206Z",
"job_client_activity_total_applicants": 0,
"job_client_activity_total_hired": 140,
"job_client_activity_total_invited_to_interview": 0,
"job_client_activity_unanswered_invites": 15,
"job_contractor_tier": "ENTRY_LEVEL",
"job_currency": "USD",
"job_description": "We’re looking for people in the U.S. to join a focus group and give feedback on the customer experience of our online materials. This one-time task takes about 30 minutes and involves reviewing our website, identifying strengths, and suggesting improvements. Your input will play a key role in helping us enhance the customer experience of our online educational resources. If you have a good eye for detail, we’d love to hear from you. Compensation for your time is $25.",
"job_fixed_budget": "25.0",
"job_fixed_duration": 3,
"job_fixed_duration_label": "Less than 1 month",
"job_hourly_duration": null,
"job_hourly_duration_label": null,
"job_hourly_max": null,
"job_hourly_min": null,
"job_hourly_type": null,
"job_id": "1955564428051706341",
"job_is_contract_to_hire": true,
"job_number_of_positions_to_hire": 50,
"job_published_at": "2025-08-13T09:38:07.565Z",
"job_qualifications": "{\"type\": \"INDEPENDENT\", \"countries\": [\"United States\"], \"prefEnglishSkill\": \"NATIVE\"}",
"job_questions": [
"This project is only open to U.S. participants. Are you a U.S. citizen currently in the United States?",
"In what U.S. state are you located?"
],
"job_skills": [
"English",
"Writing"
],
"job_title": "Quick Evaluation of Website Customer Experience | PK2",
"job_type": "FIXED",
"job_url": "https://www.upwork.com/jobs/~021955564428051706341",
"work_history": [],
"created_at": "2025-10-01 14:22:32.644644+00",
"id": "1955564428051706341"
},
"feed": {
"id": "feed_789",
"name": "React Developer Jobs"
}
}
}Payload Fields Reference
Root Payload Fields
| Field | Type | Description |
|---|---|---|
event | string | Always "job.matched" for job notifications |
webhook_id | string | Unique identifier for the webhook configuration |
timestamp | string | ISO 8601 timestamp when webhook was triggered |
data | object | Contains job and feed details |
Job Object Fields
The data.job object contains comprehensive job information from Upwork:
| Field | Type | Description |
|---|---|---|
job_id | string | Unique Upwork job identifier |
job_title | string | Job title as posted by client |
job_description | string | Full job description text |
job_url | string | Direct link to the Upwork job posting |
job_type | string | Job type: "FIXED" or "HOURLY" |
job_published_at | string | ISO 8601 timestamp when job was posted |
job_skills | array | Required skills for the job |
job_category | string | Upwork job category slug |
job_category_group | string | Job category group slug |
job_category_group_label | string | Human-readable category group name |
job_currency | string | Currency code (e.g., "USD") |
job_fixed_budget | number | Fixed project budget (if job_type is FIXED) |
job_hourly_min | number | Minimum hourly rate (if job_type is HOURLY) |
job_hourly_max | number | Maximum hourly rate (if job_type is HOURLY) |
job_contractor_tier | string | Required experience level |
job_questions | array | Screening questions from client |
job_qualifications | object | Location and language requirements |
job_number_of_positions_to_hire | number | Number of freelancers to hire |
job_is_contract_to_hire | boolean | Whether job may become long-term |
Client Information Fields
Client details are included in the job object with client_* prefixed fields:
| Field | Type | Description |
|---|---|---|
client_country | string | Client's country |
client_city | string | Client's city |
client_rating | number | Client's average rating (1-5) |
client_feedback_count | number | Number of reviews received |
client_total_charges | number | Total amount spent on Upwork |
client_posted_jobs | number | Total jobs posted by client |
client_total_jobs_with_hires | number | Jobs where client hired someone |
client_payment_method_is_verified | boolean | Whether payment method is verified |
client_is_enterprise | boolean | Whether client is enterprise account |
client_active_assignments | number | Current active projects |
Job Activity Fields
Current activity and competition metrics for the job:
| Field | Type | Description |
|---|---|---|
job_client_activity_total_applicants | number | Total number of proposals submitted |
job_client_activity_total_hired | number | Number of freelancers hired for this job |
job_client_activity_invitations_sent | number | Invitations sent by client |
job_client_activity_total_invited_to_interview | number | Freelancers invited to interview |
job_client_activity_last_buyer_activity | string | Timestamp of client's last activity |
Pricing & Reliability
Pricing & Credits
Monthly included requests1,000
Cost per webhook delivery$0.007
Each webhook attempt (successful or failed) consumes 1 credit.
Reliability
Maximum retries10 attempts
Request timeout10 seconds
Retry strategyExponential backoff
Security Best Practices
Webhook Security
HTTPS Required
All webhook URLs must use HTTPS
Validate Payloads
Always validate incoming webhook payloads
Idempotent Processing
Handle duplicate deliveries gracefully using job_id
Example Webhook Handler
// Node.js Express example
app.post('/webhook/winfast', (req, res) => {
try {
const payload = req.body;
// Validate payload structure
if (!payload.webhook_id || !payload.data.job) {
return res.status(400).send('Invalid payload');
}
// Process the job notification
processJobNotification(payload);
// Respond with 200 to acknowledge receipt
res.status(200).send('OK');
} catch (error) {
console.error('Webhook error:', error);
res.status(500).send('Internal server error');
}
});Troubleshooting
Common Issues
Webhook Not Receiving Notifications
- Verify your endpoint URL is accessible and returns 200 status
- Check that your feed criteria match available jobs
- Ensure webhook is enabled and has sufficient credits
- Confirm HTTPS is properly configured
Webhook Disabled Automatically
- Check webhook credit balance in dashboard
- Review webhook event logs for repeated failures
- Verify endpoint is responding within 10-second timeout
- Ensure endpoint returns proper HTTP status codes
Duplicate Notifications
- Implement idempotent processing using job_id
- Store processed job_ids to prevent duplicates
- Check for network issues causing retry attempts
Ready to Get Started?
Set up your first webhook in minutes and start receiving real-time job notifications that match your criteria.
Need Help or Have Questions?
Our support team is here to help you with any questions about Winfast, your account, or these policies.
Email Support
Get detailed help via email
Quick Response
Usually within 24 hours
Privacy First
Your data stays secure
Email us at john@winfast.app