# HireHive Webhooks

[HireHive](https://hirehive.com) 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)

| Header | Value |
| --- | --- |
| `webhook-id` | Identifies the message; retries reuse it. Your idempotency key (the body has no event id) |
| `webhook-timestamp` | Unix seconds |
| `webhook-signature` | One 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:

```javascript
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](https://github.com/hookdeck/webhook-skills/blob/main/skills/hirehive-webhooks/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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/hirehive-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/hirehive-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/hirehive-webhooks/examples/fastapi/).

## Event Type and Payload

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

```json
{
  "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

| Event | Fired when |
| --- | --- |
| `job.created` / `job.updated` / `job.deleted` | A job is created, updated or deleted |
| `job.status.updated` | The status of a job changes |
| `application.created` | A new application is created |
| `application.stage.updated` | An application moves to another stage |
| `application.deleted` | An application is deleted |
| `candidate.updated` | A candidate's details are updated |
| `candidate.note.created` / `.updated` / `.deleted` | A note on a candidate is added, edited or removed |
| `candidate.tag.added` / `candidate.tag.removed` | A tag is added to or removed from a candidate |
| `feedback.requested` | Feedback is requested for an application |
| `feedback.submitted` / `feedback.updated` | A feedback form is completed or updated |
| `interview.created` / `interview.updated` / `interview.cancelled` | An 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](https://github.com/hookdeck/webhook-skills/blob/main/skills/hirehive-webhooks/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

```bash
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

```bash
# 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

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/hirehive-webhooks/references/overview.md) - Event catalog, body shape and delivery behaviour
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/hirehive-webhooks/references/setup.md) - Create a webhook, find the secret, test
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/hirehive-webhooks/references/verification.md) - Library and manual verification, gotchas, debugging