Agent skill
HackerOne Webhooks Skill
Receive and verify HackerOne webhooks. Use when setting up a HackerOne webhook endpoint, debugging X-H1-Signature verification failures, or handling report events like report_created, report_triaged, report_bounty_awarded and report_resolved from bug bounty and vulnerability disclosure programs.
Install this skill
npx skills add hookdeck/webhook-skills --skill 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-Signatureheader? - Why does my HackerOne webhook signature verification fail?
- How do I handle
report_created,report_triagedorreport_bounty_awardedevents? - 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.
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.
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/, examples/nextjs/, 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_, report_, report_closed_as_spam, report_ | A report is closed with that state |
HackerOne documents more events (retests, disclosure, swag, assignment, program_hacker_joined and others); see 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
HACKERONE_WEBHOOK_SECRET=your_webhook_secret # the secret set on the HackerOne webhook
Local Development
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 - Events, headers, payload shape
- references/setup.md - Creating the webhook and secret
- references/verification.md - Signature check in Node, Python and Next.js, gotchas
- examples/ - Runnable Express, Next.js and FastAPI handlers with tests