Guide to HackerOne Webhooks: Features and Best Practices
HackerOne runs bug bounty and vulnerability disclosure programmes, where security researchers submit reports and the programme's team triages, rewards and resolves them. Security teams usually track the fix somewhere else: Jira, GitHub, an internal tracker or a chat channel. HackerOne webhooks connect the two by sending report and programme activity to your own endpoint as it happens.
You'll learn where HackerOne puts the event name, what the JSON:API body contains, why you must set a secret before the signature means anything, and how to handle a delivery policy HackerOne doesn't document.
What are HackerOne webhooks?
HackerOne webhooks are created at programme level. A webhook acts with the permissions of the user who created it, so if that user loses access to a report or leaves the programme, the webhook's view changes too. Create webhooks from an account whose access matches what the integration should see.
Each webhook subscribes to a set of events. HackerOne recommends subscribing only to the ones you handle, which keeps the number of requests down. When a subscribed event occurs, HackerOne sends a JSON POST describing the activity and the report it belongs to.
HackerOne webhook features
| Feature | Details |
|---|---|
| Signature | hex HMAC-SHA256 |
| Signature header | x-h1-signature |
| Body | JSON |
| Event routing | Header field X-H1-Event |
Each delivery has three HackerOne headers:
X-H1-Eventnames the event.X-H1-Deliveryis a GUID that identifies the delivery.X-H1-Signatureissha256=followed by a hex HMAC-SHA256 of the body.
HackerOne's webhook documentation does not describe retries, timeouts, expected status codes or source IP addresses.
Events and payloads
Only the header names the event. The body is {data: {activity, report}} (JSON:API-style); data.activity.type (e.g. activity-bug-filed) is an activity type, not the webhook event name, and the mapping between the two is not documented.
| Documented event | Meaning |
|---|---|
report_ | Triggers when a report is agreed to be publicly disclosed. |
report_bounty_awarded | Triggers when a hacker is awarded a bounty as a result of their report. |
report_bounty_suggested | Triggers when a bounty is suggested against a report. |
report_ | Triggers when a report is closed as a duplicate of another report. |
report_ | Triggers when a report is closed as informative. |
report_closed_as_spam | Triggers when a report is closed as spam. |
report_ | Triggers when a report is closed as not applicable. |
report_comment_created | Triggers each time a comment is created on a report. |
These are 8 of the 32 events HackerOne lists. The others include report_created, report_triaged, report_resolved, report_reopened, report_needs_more_info, report_user_assigned, report_group_assigned, report_became_public, the report_retest_* events, and program_hacker_joined and program_hacker_left.
HackerOne's example delivery, cut down, looks like this:
{
"data": {
"activity": {
"type": "activity-bug-filed",
"id": "1337",
"attributes": {
"message": "",
"created_at": "2020-02-25T08:05:21.674Z",
"internal": false
},
"relationships": {
"actor": {
"data": { "id": "1", "type": "user", "attributes": { "username": "hacker" } }
}
}
},
"report": {
"id": "548",
"type": "report",
"attributes": {
"title": "Critical vulnerability!",
"state": "new",
"vulnerability_information": "## Summary: ...",
"triaged_at": null,
"closed_at": null,
"bounty_awarded_at": null
},
"relationships": {
"reporter": {
"data": { "id": "1", "type": "user", "attributes": { "username": "hacker" } }
}
}
}
}
}
report.attributes.vulnerability_ is the researcher's full write-up, often with reproduction steps for an unfixed vulnerability. activity.attributes.internal tells you whether a comment is visible only to the programme team. Both matter when you forward events to a less restricted system.
Setting up HackerOne webhooks
HackerOne's API documentation describes webhook behaviour but not the settings screens, so look for the webhooks section in your programme's settings. Then:
- Enter your endpoint URL, for example
https://example.com/webhooks/hackerone. - Choose the events to subscribe to, for example
report_created,report_triagedandreport_bounty_awarded. - Set a secret, and store it in your server's configuration as
HACKERONE_WEBHOOK_SECRET.
If you receive through Hookdeck, use the same secret as the HackerOne source's verification secret. Without a secret, HackerOne signs with an empty key, which the Hookdeck source cannot verify.
If you already have a webhook with no secret and can't add one yet, leave verification off on the Hookdeck source, and treat those requests as unauthenticated until a secret is set.
To receive events locally, run the Hookdeck CLI and use the forwarding URL it prints:
npx hookdeck-cli listen 3000 hackerone --path /webhooks/hackerone
Securing HackerOne webhooks
Strip the sha256= prefix from X-H1-Signature, compute a hex HMAC-SHA256 of the raw body using the webhook's secret, and compare the two in constant time. See validating payloads in HackerOne's docs.
Node.js verification
const crypto = require('node:crypto');
function verifySignature(rawBody, headers, secret) {
if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
const signature = headers['x-h1-signature'];
if (typeof signature !== 'string') return false;
const key = Buffer.from(secret, 'utf8');
const message = rawBody;
const candidates = [signature.startsWith('sha256=') ? signature.slice(7) : signature];
const expected = crypto.createHmac('sha256', key).update(message).digest();
return candidates.some((candidate) => {
if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
const received = Buffer.from(candidate, 'hex');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
The function refuses an empty secret on purpose. An HMAC keyed with '' can be produced by anyone, so accepting it would mean accepting any request.
The handler reads the event name from the header and keys each delivery on X-H1-Delivery:
const express = require('express');
const app = express();
app.post('/webhooks/hackerone', express.raw({ type: '*/*' }), async (req, res) => {
const secret = process.env.HACKERONE_WEBHOOK_SECRET;
if (!secret) return res.sendStatus(500);
if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
const eventName = req.get('x-h1-event');
const deliveryId = req.get('x-h1-delivery');
let parsed;
try {
parsed = JSON.parse(req.body.toString('utf8'));
} catch {
return res.sendStatus(400);
}
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return res.sendStatus(400);
const { data } = parsed;
if (!data || typeof data !== 'object') return res.sendStatus(400);
try {
await recordHackerOneDelivery(deliveryId, {
event: eventName,
reportId: data.report?.id,
reportState: data.report?.attributes?.state,
internal: data.activity?.attributes?.internal ?? null,
payload: data,
});
} catch {
return res.sendStatus(503);
}
res.sendStatus(200);
});
recordHackerOneDelivery should ignore a delivery ID it has seen before. A worker can then update the ticket linked to reportId, taking care not to copy internal comments or vulnerability_ anywhere with wider access.
No timestamp is signed, so the signature doesn't show when a request was made. Hookdeck's HackerOne source verifies the same sha256= HMAC when a secret is configured, answers HackerOne with 200, and marks mismatched requests as failed verification.
Make HackerOne webhooks production-ready. Hookdeck Event Gateway checks
X-H1-Signature, keeps every report event, and retries delivery to your tracker, so a Jira outage doesn't leave a triaged vulnerability without a ticket.
HackerOne webhook limitations and pain points
The secret is optional
The Problem: A webhook created without a secret sends signatures that prove nothing.
Why It Happens: HackerOne signs with an empty-string key when no secret is set, so anyone who knows your URL can produce a valid signature.
Workarounds:
- Always set a secret. HackerOne recommends it for every webhook.
- Reject requests in your receiver when no secret is configured, as the example does.
How Hookdeck Can Help: A Hookdeck source configured with the secret records any request with a wrong or empty-key signature as failed verification, so it is kept apart from the verified events your tracker receives.
Delivery behaviour is undocumented
The Problem: You don't know whether HackerOne retries a failed delivery, how long it waits, or which status codes count as success.
Why It Happens: HackerOne's webhook documentation covers events, headers and signatures, but not retries, timeouts or status codes.
Workarounds:
- Return
200quickly and do the work afterwards. - Reconcile against the HackerOne API after an outage, for example by fetching reports updated since the last event you processed.
How Hookdeck Can Help: Hookdeck takes HackerOne's request immediately and handles retries to your service under a policy you set, so HackerOne's behaviour after a failure stops mattering.
Event names and activity types don't line up
The Problem: The body says activity-bug-filed, the header says report_created, and you're not sure which to trust.
Why It Happens: The body describes a HackerOne activity in JSON:API form. The webhook event name exists only in X-H1-Event, and HackerOne doesn't document how the two map.
Workarounds:
- Route on
X-H1-Eventand use the body for data only. - Persist the header with the body so you can replay a stored event with its name intact.
How Hookdeck Can Help: Hookdeck filters can match on the x-h1-event header, sending bounty events to finance and triage events to engineering from one webhook.
Webhooks inherit a user's permissions
The Problem: A webhook stops seeing reports after a change to its creator's account.
Why It Happens: Webhooks are bound to the permissions of the user who created them.
Workarounds:
- Create webhooks from an account reserved for integrations, with access that matches the integration.
- Review webhook owners when people leave the team.
How Hookdeck Can Help: Hookdeck's request history shows when deliveries for a programme change or stop, which is often the first sign of a permissions change.
Best practices
Keep sensitive content contained
Reports describe vulnerabilities that may not be fixed yet. Forward only the fields a downstream system needs, and drop internal comments before sending anything to a wider audience.
Deduplicate on X-H1-Delivery
Each delivery has a GUID. Storing it with a unique constraint guards against repeats, following the approach in our webhook idempotency guide.
Hand off to a worker
Creating a Jira issue or posting to Slack can be slow or fail. Record the delivery, return 200, and run integrations from a queue, as covered in processing webhooks asynchronously.
Subscribe narrowly
With 32 events available, subscribe only to those your integration uses. It reduces traffic and keeps report data out of systems that don't need it.
Conclusion
HackerOne webhooks report activity on your programme's reports, naming the event in X-H1-Event and signing the body in X-H1-Signature. The signature only means something if you set a secret. Verify the raw body, key each delivery on X-H1-Delivery, and assume nothing about retries, since HackerOne doesn't document them.
Hookdeck Event Gateway gives HackerOne events a durable record and a retry policy you can see and control.
Get started with Hookdeck for free and handle HackerOne webhooks reliably in minutes.