Guide to HireHive Webhooks: Features and Best Practices
HireHive is an applicant tracking system for teams that hire regularly: it publishes jobs, collects applications, moves candidates through stages and gathers interview feedback. Its webhooks let the rest of your stack follow along. A new application can open a record in your HRIS, a candidate reaching the offer stage can trigger a contract, and a scheduled interview can land in a calendar.
This guide covers HireHive's 19 recruiting events, creating webhooks and finding their secrets, verifying the Standard Webhooks signature, and HireHive's long retry schedule.
What are HireHive webhooks?
In HireHive you can create as many webhooks as you like. Each has a URL, listens to one or more events, has its own signing secret, and can be switched on and off. HireHive keeps a log of requests sent to each webhook and can resend them. API endpoints for listing, creating and updating webhooks are also available.
HireHive says it follows the Standard Webhooks specification "for the header signature and payload of webhook request". It prints the webhook-id, webhook-timestamp and webhook-signature headers and a standardwebhooks library call, but not the HTTP method, the Content-Type or the signing construction; those come from the specification. The body is a three-field envelope: type, timestamp and data.
HireHive webhook features
| Feature | Details |
|---|---|
| Configuration | Webhook settings in HireHive (manage-webhooks permission), or the API |
| Webhooks | Unlimited. Each listens to one or more events and can be disabled |
| Signature | Standard Webhooks HMAC-SHA256 |
| Headers | webhook-id, webhook-timestamp (Unix seconds), webhook-signature |
| Secret | One per webhook, in its settings. Format not stated in text (whsec_ in the demo video) |
| Body | {type, timestamp, data} |
| Event routing | Body field type. No header carries it |
| Response window | 2xx within 30 seconds |
| Retries | 30 seconds, 5 minutes, 30 minutes, 2, 5, 10, 14, 20 and 24 hours (about 75.5 hours) |
| Request log | Per webhook, with resend |
| Ordering, disabling | Not documented |
| Source IPs | Not published |
Events and payloads
| Field | Meaning |
|---|---|
type | The event type, for example application.created. This is what handlers switch on |
timestamp | ISO 8601 time the event occurred |
data | The object the event is about |
The body has no event ID. webhook-id is unique per message and survives retries, so use it to deduplicate.
Common Event Types
| Event | Triggered When | Common Use Cases |
|---|---|---|
job.created | A job is created | Publish it on your careers site |
job.updated | A job is updated | Refresh the listing |
job.status.updated | The status of a job changes | Show or hide the job on your site |
job.deleted | A job is deleted | Remove the listing |
application.created | A new application is created | Create a record in your HRIS or CRM, notify the team |
application.stage.updated | An application moves to another stage | Send a contract offer when a candidate reaches a stage |
application.deleted | An application is deleted | Remove synced records |
candidate.updated | A candidate's details are updated | Sync contact details |
candidate.note.created | A note is added to a candidate | Mirror notes elsewhere |
candidate.note.updated | A candidate note is updated | Update the mirrored note |
candidate.note.deleted | A candidate note is deleted | Delete the mirrored note |
candidate.tag.added | A tag is added to a candidate | Trigger tag-based workflows |
candidate.tag.removed | A tag is removed from a candidate | Undo tag-based workflows |
feedback.requested | Feedback is requested for an application | Remind the reviewer |
feedback.submitted | A feedback form is completed | Collect scores |
feedback.updated | A feedback form is updated | Refresh scores |
interview.created | An interview is created | Add a calendar entry |
interview.updated | An interview is updated | Reschedule the entry |
interview.cancelled | An interview is cancelled | Remove the entry |
HireHive's description for job.created is a copy of the one for job.status.updated ("Occurs when the status of a job is changed"), almost certainly a docs error. HireHive's example envelope elides data, and the per-event pages have no schema in a fetchable form, so capture a real delivery of each type you handle before depending on its fields.
Setting up HireHive webhooks
HireHive documents the dashboard steps in a short video rather than text, so the labels here may differ slightly from what you see.
- Open the webhook settings in HireHive and create a webhook. You need the permission to manage webhooks.
- Enter your HTTPS URL.
- Choose the events it listens to, from one to all 19.
- Save, then copy the webhook's secret into
HIREHIVE_WEBHOOK_SECRET.
In the video the secret starts with whsec_. If yours doesn't, it is the base64 key on its own; add whsec_ in front when a tool expects that form. To create webhooks from code instead, see the webhooks API reference.
For local testing, start a tunnel with the Hookdeck CLI and use its URL for the webhook:
npx hookdeck-cli listen 3000 hirehive --path /webhooks/hirehive
With Hookdeck. Create a source of type HireHive in Hookdeck, paste the webhook's secret in whsec_ form, and use the source URL as the webhook URL. Hookdeck accepts POST only for this source. It answers HireHive with a 200 regardless of the signature result, and requests that fail the check are recorded as failed verification without being forwarded.
Securing HireHive webhooks
Under Standard Webhooks, the signed content is {webhook-id}.{webhook-timestamp}.{raw body}, the HMAC-SHA256 key is the base64-decoded secret (after removing whsec_), and webhook-signature holds one or more v1,<base64> values. The verifier below matches any of them:
const crypto = require('node:crypto');
function decodeBase64(value) {
if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
const bytes = Buffer.from(value, 'base64');
return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
? bytes : null;
}
function verifySignature(rawBody, headers, secret) {
if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
const prefix = headers['webhook-id'] !== undefined ? 'webhook' : 'svix';
const id = headers[`${prefix}-id`];
const timestamp = headers[`${prefix}-timestamp`];
const signature = headers[`${prefix}-signature`];
if (typeof id !== 'string' || !id || typeof timestamp !== 'string' ||
!/^[0-9]+$/.test(timestamp) || typeof signature !== 'string') return false;
const key = decodeBase64(secret.replace(/^whsec_/, ''));
if (!key) return false;
const message = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, 'utf8'), rawBody]);
const candidates = signature.split(/\s+/).filter((item) => item.startsWith('v1,')).map((item) => item.slice(3));
const expected = crypto.createHmac('sha256', key).update(message).digest();
return candidates.some((candidate) => {
const received = decodeBase64(candidate);
if (!received) return false;
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
Because every webhook has its own secret, a receiver that serves several HireHive webhooks needs to know which secret applies. Giving each webhook its own route keeps that simple:
const express = require('express');
// Returns the parsed body when it is a JSON object, otherwise null.
function parseJsonObject(rawBody) {
try {
const value = JSON.parse(rawBody.toString('utf8'));
return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
} catch {
return null;
}
}
const app = express();
const SECRETS = {
hris: process.env.HIREHIVE_HRIS_WEBHOOK_SECRET,
calendar: process.env.HIREHIVE_CALENDAR_WEBHOOK_SECRET,
};
app.post('/webhooks/hirehive/:name', express.raw({ type: '*/*' }), async (req, res) => {
const secret = SECRETS[req.params.name];
if (!secret) return res.sendStatus(500);
if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
const payload = parseJsonObject(req.body);
if (!payload) return res.sendStatus(400); // signed, but not a JSON object
const { type, data } = payload;
if (typeof type !== 'string') return res.sendStatus(400);
try {
await recruitingEvents.add({ messageId: req.headers['webhook-id'], type, data });
} catch {
return res.sendStatus(503); // not processed, so don't acknowledge
}
return res.sendStatus(200);
});
recruitingEvents stands in for your own queue.
HireHive doesn't set a timestamp tolerance; the standardwebhooks library it recommends allows 5 minutes. HireHive's own retries and resends keep the original webhook-timestamp, so the library would reject a delivery retried 30 minutes later. The same applies behind Hookdeck, which has no tolerance and replays with the original headers. A signature-only check avoids the problem; if you want an age limit for direct traffic, make it longer than HireHive's 24-hour last retry interval.
Make HireHive webhooks production-ready. Hookdeck Event Gateway verifies each HireHive webhook with its own secret, stores the application and interview events, and delivers them to your services with retries you control.
HireHive webhook limitations and pain points
Late retries fail the library's window
The Problem: Verification starts failing during an outage, just as HireHive retries.
Why It Happens: HireHive's retries run for about 75.5 hours and keep the original timestamp. The standardwebhooks library rejects anything older than 5 minutes.
Workarounds:
- Verify the signature without the age check, as above, or set the window wider than the retry schedule.
- Deduplicate on
webhook-idto cover replays.
How Hookdeck Can Help: Hookdeck verifies each request as it arrives and applies no timestamp tolerance, so retried and replayed events reach your service with their original, valid signatures.
The secret format is unclear
The Problem: The secret you copied doesn't verify anything.
Why It Happens: HireHive's text never shows the secret. The demo video shows a whsec_ value, and the library example calls it base64_secret. Tools that only decode whsec_ secrets will mishandle a bare base64 one.
Workarounds:
- Note whether the secret starts with
whsec_, and add the prefix if a library or gateway expects it.
How Hookdeck Can Help: Failed verifications show up in Hookdeck immediately, which makes a wrong secret obvious on the first delivery.
One secret per webhook
The Problem: A single endpoint for several webhooks can't verify all of them with one secret.
Why It Happens: Each HireHive webhook has its own secret.
Workarounds:
- Use one route per webhook, or consolidate events onto fewer webhooks.
How Hookdeck Can Help: Create a Hookdeck source per HireHive webhook, each with its secret, and route all of them to the same destination.
No ordering or disabling rules
The Problem: A stage change arrives before the application it belongs to, or a webhook stops without warning.
Why It Happens: HireHive doesn't document ordering or what happens after its last retry.
Workarounds:
- Order by the body's
timestamp, and create a placeholder when an event references an application you haven't seen. - Check the request log after outages and resend anything that failed.
How Hookdeck Can Help: Hookdeck's event history and issues make failed or missing deliveries visible without checking HireHive's log by hand.
Best practices
Verify before parsing
Read the raw bytes with express.raw({ type: '*/*' }), await request.text() in a Next.js handler, or await request.body() in FastAPI. HireHive prints no Content-Type, so a raw parser that accepts any type is the safe choice.
Answer inside 30 seconds
Store the event and return 2xx, then sync to your HRIS or calendar in a worker. See why to process webhooks asynchronously.
Treat candidate data carefully
Candidate events carry personal data. Keep payloads out of general-purpose logs and delete mirrored records when application.deleted arrives.
Deduplicate on webhook-id
The body has no ID, and HireHive retries up to nine times. Our idempotency guide covers storage patterns.
Conclusion
HireHive gives each webhook its own secret, a Standard Webhooks signature and one of the longer retry schedules around, at over three days. That schedule is the main design constraint: the default 5-minute library window will reject its later retries. Verify on signature alone, deduplicate on webhook-id, keep a route or source per webhook, and capture real payloads, because HireHive's docs don't show them in full.
If you'd rather not run that receiver yourself, Hookdeck Event Gateway can verify HireHive's webhooks and queue each recruiting event for your services. Sign up free to add a HireHive source.