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-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.

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-EventTriggered When
report_createdA hacker submits a new vulnerability report
report_newA report changed in a way that needs program input
report_triagedA report is triaged
report_bounty_awardedA hacker is awarded a bounty
report_comment_createdA comment is created on a report
report_resolvedA report is resolved
report_closed_as_duplicate, report_closed_as_informative, report_closed_as_spam, report_closed_as_not_applicableA 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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →