Webhooks Integration

Zenfl allows you to receive job alerts via webhooks, enabling seamless integration with your own applications, services, or workflow tools. This document covers everything you need to know about setting up and using Zenfl webhooks.

SUBSCRIPTION REQUIRED

• Webhooks are only available for paid subscribers and not available on free trial accounts
• 1,000 webhook requests per month are included in your subscription
• Additional requests are billed at $0.01 per job alert

What Are Webhooks?

Webhooks provide a way for applications to communicate with each other in real-time. When a new job matching your feed criteria is found, Zenfl can automatically send the job data to a URL you specify (your webhook endpoint).

Use Cases

• Custom Applications: Integrate job alerts into your own applications
• Automation: Trigger automated actions when new jobs appear
• Data Collection: Gather job data for analysis or reporting
• Workflow Integration: Connect with tools like Zapier, Make, or n8n
• Team Coordination: Share job opportunities with team members via custom channels

Setting Up Webhooks

You can set up webhooks at two levels:

Account-Level Webhooks

These receive ALL job alerts from all your feeds in a single endpoint.

1. Contact Zenfl support to set up an account-level webhook
2. Provide your webhook URL
3. Start receiving all job notifications at your endpoint

Feed-Level Webhooks

These receive only job alerts from a specific feed.

1. Open the Telegram mini-app using the Zenfl bot
2. Select or create a feed
3. Scroll down to the "Webhook URL" field
4. Enter the URL where you want to receive notifications
5. Save your feed settings

IMPORTANT

If you have both account-level and feed-level webhooks configured, jobs matching a feed with a specific webhook URL will be sent ONLY to that feed-level webhook, not to your account-level webhook.

Webhook Payload Structure

When Zenfl sends a job to your webhook, it includes a structured JSON payload containing all relevant job details.

Webhook Payload TypeScript Definition

Below is the TypeScript definition of the data sent via webhook:

// Feed-specific webhook payload type
type FeedWebhookPayload = {
  // Job fields
  createdAt: string;
  updatedAt: string;
  postedAt: string;
  categoryGroup: string | null;
  category: string | null;
  title: string | null;
  description: string | null;
  locationCheckRequired: boolean | null;
  countries: string[];
  regions: string[];
  budget: number | null;
  budgetType: "FIXED" | "HOURLY" | null;
  hourlyFrom: number | null;
  hourlyTo: number | null;
  more30HoursPerWeek: boolean | null;
  featured: boolean | null;
  experience: "ENTRY" | "INTERMEDIATE" | "EXPERT" | null;
  oneTimeProject: boolean | null;
  onGoingProject: boolean | null;
  contractToHire: boolean | null;
  questions: string[];
  skills: string[];
  url: string | null;

  // Client fields
  clientRating: number | null;
  clientReviewsCount: number | null;
  clientCountry: string | null;
  clientTotalJobs: number | null;
  clientTotalHires: number | null;
  clientSpent: number | null;
  clientHireRate: number | null;
  clientAverageRate: number | null;
  clientPaymentVerified: boolean | null;
  clientEnterprise: boolean | null;
  clientSignUpDate: string | null;
  connectsCost: number | null;

  // Feed-specific fields
  feedName: string;
  hashTags: string[]; // without # symbol
  text: string;
};

// Account-level webhook payload type includes feed names array
type AccountWebhookPayload = Omit<FeedWebhookPayload, "feedName"> & {
  feedNames: string[]; // Array of all matching feed names
};

Feed-Specific Webhook Payload

{
  "createdAt": "2023-11-28T14:32:15.000Z",
  "updatedAt": "2023-11-28T14:32:15.000Z",
  "postedAt": "2023-11-28T14:32:15.000Z",
  "categoryGroup": "Web, Mobile & Software Dev",
  "category": "Web Development",
  "title": "Looking for React Developer for E-commerce Project",
  "description": "We need an experienced React developer to help build...",
  "locationCheckRequired": false,
  "countries": ["United States"],
  "regions": [],
  "budget": 500,
  "budgetType": "FIXED",
  "hourlyFrom": null,
  "hourlyTo": null,
  "more30HoursPerWeek": false,
  "featured": false,
  "experience": "INTERMEDIATE",
  "oneTimeProject": true,
  "onGoingProject": false,
  "contractToHire": false,
  "questions": ["What relevant experience do you have?", "When can you start?"],
  "skills": ["React", "JavaScript", "CSS", "HTML"],
  "url": "https://www.upwork.com/jobs/~123456789",
  "clientRating": 4.92,
  "clientReviewsCount": 15,
  "clientCountry": "United States",
  "clientTotalJobs": 25,
  "clientTotalHires": 22,
  "clientSpent": 10000,
  "clientHireRate": 88,
  "clientAverageRate": 45,
  "clientPaymentVerified": true,
  "clientEnterprise": false,
  "clientSignUpDate": "2020-06-15T00:00:00.000Z",
  "connectsCost": 4,
  "feedName": "React Developer Jobs",
  "hashTags": ["react", "frontend", "webdev"],
  "text": "New job alert from Zenfl! 🚀"
}

Account-Level Webhook Payload

For general account webhooks, the payload includes all the same job details, but adds:

{
  // ... all job properties shown above
  "feedNames": ["React Developer Jobs", "Frontend Work"], // All matching feeds
  "hashTags": ["react", "frontend", "webdev", "ui"], // Combined hashtags from all feeds (without # symbol)
  "text": "New job alert from Zenfl! 🚀"
}

Webhook Job Properties Reference

Property	Type	Description
title	String	Job posting title
description	String	Full job description
url	String	Direct link to the job
budget	Number	Fixed budget amount (if applicable)
budgetType	String	"FIXED" or "HOURLY"
hourlyFrom	Number	Minimum hourly rate (if hourly)
hourlyTo	Number	Maximum hourly rate (if hourly)
categoryGroup	String	Main category group
category	String	Specific job category
countries	Array	Countries where the job is available
skills	Array	Required skills for the job
clientCountry	String	Client's country
clientRating	Number	Client's average rating (0-5)
clientReviewsCount	Number	Number of reviews the client has received
clientTotalJobs	Number	Total jobs the client has posted
clientTotalHires	Number	Total freelancers the client has hired
clientSpent	Number	Total amount the client has spent
clientSpentMax	Number	Maximum amount for client's total spend (feed-specific filter)
clientHireRate	Number	Percentage of job postings that result in hires
clientAverageRate	Number	Average hourly rate paid by the client
clientPaymentVerified	Boolean	Whether client has verified payment method
clientEnterprise	Boolean	Whether client is an enterprise account
clientSignUpDate	String	ISO date when client joined the platform
postedAt	String	ISO date when job was posted
createdAt	String	ISO date when job was created in our system
updatedAt	String	ISO date when job was last updated in our system
locationCheckRequired	Boolean	Whether location check is required for this job
regions	Array	Regions where the job is available
experience	String	Required experience level ("ENTRY", "INTERMEDIATE", "EXPERT")
connectsCost	Number	Number of connects required to apply
more30HoursPerWeek	Boolean	Whether job requires more than 30 hours per week
oneTimeProject	Boolean	Whether job is a one-time project
onGoingProject	Boolean	Whether job is an ongoing project
contractToHire	Boolean	Whether job is a contract-to-hire opportunity
questions	Array	Client's screening questions
featured	Boolean	Whether job is featured
feedName	String	Name of the feed that matched (feed-specific webhooks only)
feedNames	Array	Names of all feeds that matched (account-level webhooks only)
hashTags	Array	Hashtags associated with matching feed(s) (without # symbol)
text	String	Standard notification text

Building a Webhook Receiver

Your webhook endpoint should be able to:

1. Accept POST requests with JSON payloads
2. Return a 200 OK status code quickly (within 10 seconds)
3. Process the job data asynchronously if needed

Example Webhook Receiver (Node.js)

const express = require("express");
const app = express();
app.use(express.json());

app.post("/webhook/zenfl", (req, res) => {
  const jobData = req.body;

  // Immediately respond to acknowledge receipt
  res.status(200).send("OK");

  // Process job data asynchronously
  processJobData(jobData);
});

function processJobData(job) {
  // Example: Log new job
  console.log(`New job received: ${job.title}`);

  // Example: Send to Slack
  if (job.hourlyFrom > 50) {
    sendToSlack(
      `High-paying job alert: ${job.title} ($${job.hourlyFrom}+/hr) - ${job.url}`,
    );
  }

  // Example: Store in database
  saveJobToDatabase(job);
}

app.listen(3000, () => {
  console.log("Webhook receiver running on port 3000");
});

Webhook Best Practices

Security

• Use HTTPS: Always use HTTPS URLs for your webhook endpoints
• Add Authentication: Consider adding a token or signature to verify webhook sources
• Validate Data: Always validate incoming webhook data before processing

Reliability

• Respond Quickly: Your endpoint should acknowledge receipt within 10 seconds
• Implement Retry Logic: Be prepared to handle and retry failed webhook deliveries
• Monitor Webhook Health: Track webhook delivery success rates

Performance

• Process Asynchronously: Acknowledge receipt immediately, then process data
• Handle Duplicates: Implement idempotent processing in case of duplicate deliveries
• Scale Appropriately: Be prepared for potential spikes in webhook volume

Frequently Asked Questions

What happens if my webhook endpoint is down?

Zenfl will attempt to deliver webhooks up to 10 times with increasing delays between retries. After 10 consecutive failures, the webhook URL will be automatically disabled and you'll need to re-enable it once your endpoint is operational again.

Is there a limit to how many webhooks I can receive?

Your subscription includes 1,000 webhook requests per month. Additional requests are billed at $0.01 per job alert. Please note that webhooks are only available for paid subscribers and not available on free trial accounts.

Can I receive webhooks for multiple feeds at the same URL?

Yes, you can use the same webhook URL for multiple feeds, or set up an account-level webhook to receive all alerts in one place.

How quickly will I receive job alerts via webhook?

Webhook deliveries typically occur within seconds of a job being found, though exact timing depends on system load and job processing rates.

Can I test my webhook endpoint?

Yes, you can set up a test feed with very specific criteria to trigger occasional webhooks for testing, or contact support for a test webhook delivery.

Integration Examples

Zapier Integration

1. Create a webhook trigger in Zapier
2. Use the provided webhook URL in your Zenfl feed
3. Set up actions based on job properties, such as:
   • Add high-paying jobs to a special Trello list
   • Send jobs from specific clients to a dedicated Slack channel
   • Create calendar events for application deadlines

Slack Integration

1. Create a Slack app with an incoming webhook
2. Set up your webhook receiver to forward specific jobs to Slack
3. Format job details for better readability in Slack
4. Use Slack's block kit to create interactive job cards

Custom Database Integration

1. Set up a webhook receiver that connects to your database
2. Store incoming jobs with relevant metadata
3. Track which jobs you've applied to and their status
4. Generate reports on job trends and opportunities

Need Help?

If you encounter any issues setting up or using webhooks:

1. Check that your webhook URL is correct and accessible
2. Verify your endpoint returns a 200 status code upon receipt
3. Contact support for assistance with webhook configuration or delivery issues