# HackerOne Webhooks

HackerOne (hackerone.com) sends an HTTP POST to a URL you configure when report and program events occur. Each delivery carries an `X-H1-Signature` header: `sha256=` followed by the lowercase hex HMAC-SHA256 of the raw request body, keyed with the secret you set on the webhook.

## When to Use This Skill

* How do I receive HackerOne webhooks?
* How do I verify the `X-H1-Signature` header?
* Why does my HackerOne webhook signature verification fail?
* How do I handle `report_created`, `report_triaged` or `report_bounty_awarded` events?
* What happens if I don't set a secret on a HackerOne webhook?

## Verification (core)

Set a secret on the HackerOne webhook and paste it here. Without one, HackerOne signs with an empty key, which this source cannot verify.

Only the raw body is signed: no timestamp, delivery ID or other header. The HMAC key is the secret's UTF-8 bytes, used as-is.

```javascript
const crypto = require('crypto');

function verifyHackerOne(rawBody, signatureHeader, secret) {
  if (!secret || !Buffer.isBuffer(rawBody) || typeof signatureHeader !== 'string') return false;
  let digest = signatureHeader.trim();
  if (digest.startsWith('sha256=')) digest = digest.slice('sha256='.length); // bare digest also accepted
  if (!/^[0-9a-fA-F]{64}$/.test(digest)) return false; // validate before decoding
  const expected = crypto.createHmac('sha256', Buffer.from(secret, 'utf8')).update(rawBody).digest();
  const received = Buffer.from(digest.toLowerCase(), 'hex');
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}
// rawBody = the exact bytes received (express.raw({ type: '*/*' })); header = req.headers['x-h1-signature']

```

Return `401` for a missing, empty or malformed header or a mismatch. Parse the JSON only after the check, and dispatch on the `X-H1-Event` header. Python and Next.js equivalents are in [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/hackerone-webhooks/references/verification.md).

There is no timestamp in the signature, so there is no replay window to check. Make handlers idempotent using the `X-H1-Delivery` GUID.

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/hackerone-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/hackerone-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/hackerone-webhooks/examples/fastapi/).

## Event Types

The event name is only in the `X-H1-Event` header. The body is `{ "data": { "activity": {...}, "report": {...} } }`; `data.activity.type` (for example `activity-bug-filed`) is an activity type, not the webhook event name.

| `X-H1-Event` | Triggered When |
| --- | --- |
| `report_created` | A hacker submits a new vulnerability report |
| `report_new` | A report changed in a way that needs program input |
| `report_triaged` | A report is triaged |
| `report_bounty_awarded` | A hacker is awarded a bounty |
| `report_comment_created` | A comment is created on a report |
| `report_resolved` | A report is resolved |
| `report_closed_as_duplicate`, `report_closed_as_informative`, `report_closed_as_spam`, `report_closed_as_not_applicable` | A report is closed with that state |

HackerOne documents more events (retests, disclosure, swag, assignment, `program_hacker_joined` and others); see [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/hackerone-webhooks/references/overview.md) for the full list. The examples handle the ones above and log the rest.

HackerOne's docs do not state retry behaviour, timeouts or success status codes, so return `2xx` quickly and dedupe on `X-H1-Delivery`.

## Environment Variables

```bash
HACKERONE_WEBHOOK_SECRET=your_webhook_secret   # the secret set on the HackerOne webhook

```

## Local Development

```bash
npx hookdeck-cli listen 3000 hackerone --path /webhooks/hackerone

```

No account required. Use the printed URL as the webhook URL in HackerOne.

## Resources

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/hackerone-webhooks/references/overview.md) - Events, headers, payload shape
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/hackerone-webhooks/references/setup.md) - Creating the webhook and secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/hackerone-webhooks/references/verification.md) - Signature check in Node, Python and Next.js, gotchas
* [examples/](https://github.com/hookdeck/webhook-skills/tree/main/skills/hackerone-webhooks/examples/) - Runnable Express, Next.js and FastAPI handlers with tests