Agent skill

HireHive Webhooks Skill

Receive and verify HireHive webhooks, which follow the Standard Webhooks specification. Use when setting up a HireHive webhook endpoint for an applicant tracking system, getting the whsec_ signing secret, debugging webhook-id / webhook-timestamp / webhook-signature verification, or handling events like application.created, application.stage.updated, job.created, candidate.updated and interview.created.

Install this skill

npx skills add hookdeck/webhook-skills --skill hirehive-webhooks


HireHive is an applicant tracking system. It sends a signed JSON event to each webhook you create when jobs, applications, candidates, feedback or interviews change. Signatures follow Standard Webhooks, so each delivery carries webhook-id, webhook-timestamp and webhook-signature headers. HireHive's docs print no method or Content-Type; POST with a JSON body comes from the Standard Webhooks spec.

When to Use This Skill

  • How do I receive HireHive webhooks?
  • How do I verify a HireHive webhook signature (webhook-signature)?
  • Where do I find my HireHive webhook secret (whsec_...)?
  • How do I handle application.created, application.stage.updated, job.created or interview.created events?
  • Why is my HireHive webhook verification failing, or failing only on retries and replays?

Verification (core)

HeaderValue
webhook-idIdentifies the message; retries reuse it. Your idempotency key (the body has no event id)
webhook-timestampUnix seconds
webhook-signatureOne or more space-separated v1,<base64> entries

Signed content is {webhook-id}.{webhook-timestamp}.{raw body}, HMAC-SHA256, base64 output. The key is the base64-decoded part of the whsec_... secret after the prefix. HireHive's pages never show the secret's format; the whsec_ prefix is what its "creating a webhook" video displays. Compare against every v1, entry; ignore other versions. If webhook-id is absent, read svix-id, svix-timestamp and svix-signature instead. The examples use the standardwebhooks library (npm and PyPI), which HireHive's docs use in their code sample:

const { Webhook } = require('standardwebhooks');

// rawBody: exact request body (Buffer or string), NOT re-serialised JSON
function verifyHireHive(rawBody, headers, secret = process.env.HIREHIVE_WEBHOOK_SECRET) {
  const p = headers['webhook-id'] ? 'webhook' : 'svix'; // fall back to the svix-* names
  new Webhook(secret).verify(rawBody, {
    'webhook-id': headers[`${p}-id`],
    'webhook-timestamp': headers[`${p}-timestamp`],
    'webhook-signature': headers[`${p}-signature`],
  }, { jsonParse: false }); // throws on a bad signature or stale timestamp → respond 401
}

The library always enforces a fixed 5-minute timestamp window. Hookdeck retries and replays resend the original webhook-timestamp, so the library rejects them once they are more than 5 minutes old. HireHive's own last retries come 14 to 24 hours after the previous attempt, so this matters. If you receive through Hookdeck and need late retries to pass, use the manual verifier in references/verification.md, which can drop or widen the window. In Express, read the body with express.raw({ type: '*/*' }) so any content type verifies, and parse JSON only after the check.

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Event Type and Payload

Every body has three properties, and the event name is the top-level type:

{
  "type": "application.created",
  "timestamp": "2024-01-24T14:59:34.5220878Z",
  "data": { }
}

timestamp is when the event occurred (ISO 8601) and data holds the event's object. HireHive's docs elide data (they print ....), so its fields aren't documented on the overview page; log a real delivery before relying on any. No header carries the event type.

Common Event Types

EventFired when
job.created / job.updated / job.deletedA job is created, updated or deleted
job.status.updatedThe status of a job changes
application.createdA new application is created
application.stage.updatedAn application moves to another stage
application.deletedAn application is deleted
candidate.updatedA candidate's details are updated
candidate.note.created / .updated / .deletedA note on a candidate is added, edited or removed
candidate.tag.added / candidate.tag.removedA tag is added to or removed from a candidate
feedback.requestedFeedback is requested for an application
feedback.submitted / feedback.updatedA feedback form is completed or updated
interview.created / interview.updated / interview.cancelledAn interview is created, updated or cancelled

These are the 19 documented events (the list may not be exhaustive), and the examples route all of them. Ignore types you don't recognise. See references/overview.md.

Delivery Semantics

A 2xx within 30 seconds is success. Anything else (non-2xx, timeout, connection reset) is retried at +30 s, 5 min, 30 min, 2 h, 5 h, 10 h, 14 h, 20 h and 24 h, about 75.5 hours after the first attempt. Respond first and process asynchronously. Deduplicate on webhook-id. HireHive states no ordering guarantee, so use timestamp if order matters. Return 400 for missing headers and 401 for a bad signature. The dashboard shows a request log and can resend a delivery.

Environment Variables

HIREHIVE_WEBHOOK_SECRET=whsec_xxxxx   # full value, prefix included, from the webhook's settings; handlers fail closed (500) without it

Each webhook has its own secret, so use one per endpoint.

Local Development

# Express / Next.js (use 8000 for FastAPI). No install or account required.
npx hookdeck-cli listen 3000 hirehive --path /webhooks/hirehive

Set the printed URL as the webhook URL in HireHive, then trigger an event (for example create a job). No challenge or validation request is sent when you save a webhook.

Reference Materials


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →