> ## Documentation Index
> Fetch the complete documentation index at: https://www.hirebase.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Get new jobs that match your search pushed to your URL, Clay, Zapier, Make or n8n, instead of polling

A webhook is a saved job search plus a URL. When Hirebase finds a new job that matches the search, it sends that job to your URL. Use it to start an automation the moment a company in your niche opens a role, to feed a CRM or Clay table, or to alert a channel.

Need **every** new job in bulk to keep a database in sync? Poll [Job Search](https://www.hirebase.org/docs/api-reference/jobs/search-post.md) with `ingested_after` instead (see [Choosing the right API](https://www.hirebase.org/docs/guides/choosing-the-right-api.md)). Webhooks send one event per request and are capped per day.

## Quickstart

**1. Get a URL that receives requests**

Use your own endpoint, a catch-hook URL from Clay, Zapier, Make or n8n, or a free test URL from [webhook.site](https://webhook.site). It must be `https` and reachable on the public internet (not `localhost` or a private address).

**2. Check how many events your search makes**

Free. Returns the average number of new matching jobs, and companies, per day over the last 7 days.

```bash theme={null}
curl -X POST https://api.hirebase.org/v2/webhooks/estimate \
  -H "X-API-Key: $HIREBASE_API_KEY" -H "Content-Type: application/json" \
  -d '{"search": {"job_titles": ["Registered Nurse"], "geo_locations": [{"region": "Texas", "country": "United States"}]}}'
```

**3. Create the webhook**

`search` is the same body you send to [Job Search](https://www.hirebase.org/docs/api-reference/jobs/search-post.md), without `page`, `limit`, `sort_by`, `sort_order`, `ingested_after` or `ingested_before`. Unknown fields are rejected with a `422`, so a typo can't turn into an unfiltered webhook.

```bash theme={null}
curl -X POST https://api.hirebase.org/v2/webhooks \
  -H "X-API-Key: $HIREBASE_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "url": "https://webhook.site/your-id",
    "search": {"job_titles": ["Registered Nurse"], "geo_locations": [{"region": "Texas", "country": "United States"}]},
    "events": ["company.new"],
    "max_jobs_per_day": 200
  }'
```

The response includes the webhook `id` and its signing `secret` (`whsec_...`).

**4. Send a test event**

Sends one signed `webhook.test` event with a sample matching job right away, and tells you what your endpoint answered. Free.

```bash theme={null}
curl -X POST https://api.hirebase.org/v2/webhooks/{id}/test -H "X-API-Key: $HIREBASE_API_KEY"
```

From then on, new matching jobs arrive as they enter Hirebase: usually within about 2 hours of a job first appearing in Hirebase. A webhook starts from the moment you create it; it does not send older jobs.

## Events

| Event | Sent when | `data` |
| - | - | - |
| `job.new` | A new job matches your search | `job` |
| `company.new` | A company has a new matching job and you haven't had a `company.new` for it in the last 30 days | `company`, `job` (the job that triggered it) |
| `webhook.test` | You call `/test` | `sample_type`, a sample `job` (and `company`) |

Pick one or both with `events` (default `["job.new"]`). `company.new` is the one to use for "tell me when a company starts hiring for X": one alert per company instead of one per opening.

Every request carries one event:

```json theme={null}
{
  "id": "msg_6af1c0d4be24a9f1e24d76f0",
  "type": "company.new",
  "created_at": "2026-11-09T13:15:00.412000+00:00",
  "webhook_id": "6af1c0cfbe24a9f1e24d76ef",
  "data": {
    "company": {"name": "Any Hour Services", "slug": "any-hour-services", "domain": "anyhourservices.com", "logo": "https://logos.hirebase.org/..."},
    "job": {"_id": "6af1bf7b481c7d5fa8a792f0", "job_title": "Plumbing Service Technician", "company_name": "Any Hour Services", "application_link": "https://...", "first_ingested": "2026-11-09T12:24:11.748000", "...": "same fields as a Job Search result"}
  }
}
```

Each job is sent once per webhook. A posting that closes and is reposted with the same application link isn't sent again.

## Verify the signature

Every request is signed with the [Standard Webhooks](https://www.standardwebhooks.com) scheme. The headers are `webhook-id` (the event id, the same on every retry, so use it to ignore duplicates), `webhook-timestamp` and `webhook-signature`. Any Standard Webhooks library verifies them with your `whsec_` secret.

```python Python theme={null}
# pip install standardwebhooks
from standardwebhooks.webhooks import Webhook

def handle(request):
    payload = request.body  # the raw bytes, before JSON parsing
    event = Webhook(WEBHOOK_SECRET).verify(payload, request.headers)  # raises if invalid
    ...
```

```javascript Node.js theme={null}
// npm install standardwebhooks
import { Webhook } from "standardwebhooks";

app.post("/hirebase", express.raw({ type: "application/json" }), (req, res) => {
  const event = new Webhook(process.env.WEBHOOK_SECRET).verify(req.body, req.headers); // throws if invalid
  res.sendStatus(200);
});
```

`GET /v2/webhooks/{id}` shows the secret again. `POST /v2/webhooks/{id}/rotate-secret` replaces it, and the old secret stops working right away.

Tools like Clay ask you to send a token in a header instead. Add it when you create the webhook: `"header": {"name": "x-clay-webhook-auth", "value": "your-token"}`.

## Delivery and retries

* Answer with any `2xx` within 10 seconds. Do slow work after you respond.
* Anything else (or a timeout) is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours. After that the event is marked `failed` and the job is refunded.
* Answering `410 Gone` turns the webhook off at once. So does 72 hours in which every attempt failed. Turn it back on with `PATCH /v2/webhooks/{id}` and `{"status": "active"}`.
* We send each webhook up to 50 events a minute, and don't follow redirects. A bigger backlog goes out over the following minutes.
* See every event from the last 30 days, with what your endpoint answered, at `GET /v2/webhooks/{id}/deliveries` (filter with `?status=failed`).

## Pricing and limits

* Each event costs **1 job** from your plan's jobs allowance, the same as one Job Search result. Overage plans bill overage at the usual rate.
* Creating, listing, testing and estimating webhooks is free. Failed events are refunded, and so are events still unsent after 25 days (for example while you've paused the webhook).
* `max_jobs_per_day` (default 1,000, up to 5,000) caps events per UTC day. Matches over the cap are skipped, not queued.
* On plans that stop at their allowance, the webhook pauses when the allowance runs out and resumes by itself when it resets or you upgrade. `status_reason` tells you why it's paused.
* Up to 10 webhooks per account. Webhooks use [Job Search](https://www.hirebase.org/docs/api-reference/jobs/search-post.md) filters; Neural Search isn't supported yet.

## Using Clay, Zapier, Make or n8n

Create a webhook (or catch hook) trigger in the tool, copy its URL, and use it as `url`. Each event arrives as one request, so each job or company becomes one row or one run. Keep your filters in the Hirebase `search`, not in the tool, so you only pay for jobs you want. Clay webhook sources accept 50,000 submissions each, so set `max_jobs_per_day` accordingly.

## Get told when an export finishes

[Export Jobs](https://www.hirebase.org/docs/api-reference/jobs/export-jobs.md) and [Export Expired Jobs](https://www.hirebase.org/docs/api-reference/jobs/export-expired-jobs.md) take an optional `notify_url` (https). When the export ends, we POST one signed event there instead of making you poll [Get Task Status](https://www.hirebase.org/docs/api-reference/tasks/get-task-status.md):

```json theme={null}
{
  "id": "msg_task_3f6c2a9e-...",
  "type": "task.completed",
  "created_at": "2026-11-09T15:20:04.118000+00:00",
  "data": {"task_id": "3f6c2a9e-...", "task_type": "export_job_data", "state": "finished", "result": {"...": "same as GET /v2/tasks/{task_id}"}, "error": null}
}
```

A failed or canceled export sends `task.failed`, with `error` set and `result` null. These events are signed the same way, but with your **account secret**, from `GET /v2/webhooks/account-secret`. You don't need a webhook to use `notify_url`. A few quick retries are made, so keep polling as a fallback for anything critical.

## Endpoints

| Method | Path | What it does |
| - | - | - |
| `POST` | `/v2/webhooks` | Create. Body: `url`, `search`, `events`, `max_jobs_per_day`, `header`, `description` |
| `GET` | `/v2/webhooks` | List your webhooks |
| `GET` | `/v2/webhooks/{id}` | One webhook, with its secret and `events_today` |
| `PATCH` | `/v2/webhooks/{id}` | Change any field, or set `status` to `paused` / `active`. A new `search` applies from now on |
| `DELETE` | `/v2/webhooks/{id}` | Delete. Unsent events are canceled and refunded |
| `POST` | `/v2/webhooks/{id}/test` | Send a signed sample event now |
| `POST` | `/v2/webhooks/estimate` | Matches per day for a `search` over the last 7 days |
| `POST` | `/v2/webhooks/{id}/rotate-secret` | New signing secret |
| `GET` | `/v2/webhooks/{id}/deliveries` | Last 30 days of events: status, attempts, response |
| `GET` | `/v2/webhooks/account-secret` | The secret that signs export `notify_url` events |


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