Webhooks
A webhook notifier sends an automation’s events to an HTTPS endpoint you run, as a signed JSON POST. Use it to route findings to a tool Hacktron doesn’t integrate with, through your own service or a workflow tool such as Zapier or n8n.
Deliveries follow the Standard Webhooks specification, so you can verify them with any of its libraries.
Organisation Admins add webhooks, see their signing secrets, and send test events.
Add a webhook
Add the notifier
Open the automation’s Settings tab, select Add Notifier, then Webhook. Enter your endpoint’s URL. It must start with https:// and be reachable from the internet. Hacktron doesn’t send to private or internal addresses.
Save
Select Save changes. Saving creates the webhook’s signing secret, and adds Show signing secret and Send test event to the webhook.
Copy the signing secret
Select Show signing secret, then Copy signing secret. Store it where your endpoint reads its configuration, such as an environment variable or a secrets manager. The secret starts with whsec_.
Send a test event
Select Send test event. Hacktron sends a ping event straight away, without retries, and shows the HTTP status your endpoint answered with.
Notifications without an action
An automation with New vulnerability found can run with notifiers and no action. It sends automation.finding.matched for each new finding that matches, and spends no automation credits.
Verify a delivery
Every delivery has three headers:
| Header | Value |
|---|---|
webhook-id |
The delivery’s ID, such as msg_2b3c4d5e-6f70-4a81-92a3-b4c5d6e7f809. Retries of a delivery keep its ID. |
webhook-timestamp |
When this attempt was sent, in seconds since the Unix epoch. |
webhook-signature |
v1, and the base64 HMAC-SHA256 signature. |
Check the signature before you trust a delivery, and reject one whose timestamp is more than five minutes from your clock. The Standard Webhooks libraries do both. Pass them the raw request body, as parsing and re-serialising the JSON changes the bytes that were signed.
Node.js
Install the library with npm install standardwebhooks.
import express from 'express'import { Webhook } from 'standardwebhooks'
const webhook = new Webhook(process.env.HACKTRON_WEBHOOK_SECRET)const app = express()
app.post('/webhooks/hacktron', express.raw({ type: 'application/json' }), (req, res) => { let event try { event = webhook.verify(req.body, req.headers) } catch { return res.status(400).end() } console.log(event.type, req.headers['webhook-id']) res.status(204).end()})
app.listen(3000)Python
Install the library with pip install standardwebhooks.
import os
from flask import Flask, requestfrom standardwebhooks.webhooks import Webhook, WebhookVerificationError
webhook = Webhook(os.environ["HACKTRON_WEBHOOK_SECRET"])app = Flask(__name__)
@app.post("/webhooks/hacktron")def hacktron_webhook(): try: event = webhook.verify(request.get_data(), request.headers) except WebhookVerificationError: return "", 400 print(event["type"], request.headers["webhook-id"]) return "", 204Other languages
- Join the
webhook-idheader, thewebhook-timestampheader, and the raw body with full stops:{webhook-id}.{webhook-timestamp}.{body}. - Remove
whsec_from the start of the secret and base64-decode the rest. The result is the signing key. - Compute the HMAC-SHA256 of the joined string with that key, and base64-encode it.
webhook-signatureis a list of signatures separated by spaces, each writtenv1,<signature>. Accept the delivery if yours matches one of them, using a constant-time comparison.- Reject the delivery if
webhook-timestampis more than five minutes before or after your clock.
Respond to a delivery
Answer with any 2xx status within 15 seconds. Hacktron doesn’t read the response body. If handling an event takes longer, queue the work and answer first.
Hacktron retries a delivery that gets another status, times out, or can’t connect. It makes up to 10 attempts over about 20 hours. The first retry comes after about 2.5 minutes, and each wait after that is about twice the last. Redirects aren’t followed, so a 3xx answer counts as a failure.
- To stop the retries of one delivery, answer
410 Gone. Later events are still sent. To stop them, remove the webhook. - Retries are sent to the webhook’s current URL. If you remove the webhook, its retries stop.
- An event can arrive more than once, and events can arrive out of order. Use
webhook-idto skip a delivery you’ve already handled, and the body’stimestampto order events.
Events
The body is a JSON object with the event’s type, its timestamp, and its data:
| Event | When Hacktron sends it |
|---|---|
automation.finding.matched |
An automation with no action matched a new finding. |
automation.run.started |
Apply Remediation started a remediation run for a matching finding. |
automation.run.finished |
That remediation run finished. |
automation.scan.finished |
A scheduled whitebox scan finished or couldn’t start. Login checks and skipped scans don’t send it. |
ping |
An Admin selected Send test event. |
Handle the event types you need and answer 2xx to the rest, as new types and fields may be added.
This example uses sample data.
{ "type": "automation.finding.matched", "timestamp": "2026-11-14T09:30:00.000Z", "data": { "automation": { "id": "0b9c3d6e-1f2a-4b5c-8d7e-9f0a1b2c3d4e", "name": "Critical findings to n8n", "url": "https://app.hacktron.ai/acme/automations/0b9c3d6e-1f2a-4b5c-8d7e-9f0a1b2c3d4e" }, "finding": { "id": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b", "display_id": "P12-FD-345", "title": "SQL injection in order search", "severity": "critical", "url": "https://app.hacktron.ai/acme/findings/P12-FD-345" }, "repo_url": "https://github.com/acme/shop", "run": null }}| Field | Type | Description |
|---|---|---|
type |
string | The event type. |
timestamp |
string | When the event happened, in ISO 8601. |
data.automation.id |
string | The automation’s ID. |
data.automation.name |
string | The automation’s name. |
data.automation.url |
string or null | The automation’s page in the dashboard. |
data.finding |
object or null | The finding, on automation.finding.matched, automation.run.started, and automation.run.finished. |
data.finding.id |
string | The finding’s UUID. |
data.finding.display_id |
string or null | The ID the dashboard shows, such as P12-FD-345. |
data.finding.title |
string | The finding’s title. |
data.finding.severity |
string | critical, high, medium, low, or info. |
data.finding.url |
string or null | The finding’s page in the dashboard. |
data.repo_url |
string or null | The repository the finding is in. |
data.run |
object or null | The run, on automation.run.started, automation.run.finished, and automation.scan.finished. |
data.run.id |
string | The run’s ID. When Hacktron retries a remediation run, automation.run.finished keeps the ID from automation.run.started. |
data.run.action |
string | remediation or whitebox-scan. |
data.run.status |
string | dispatched when a remediation run starts. When it finishes: pr_created, fix_ready, no_fix, false_positive, failed, or stopped_cap_exceeded. For a scan: success, failed, or blocked. |
data.run.url |
string or null | The run’s page in the dashboard. |
data.run.pr_url |
string or null | The pull request with the fix, when the run opened one. |
data.run.reason |
string or null | Why the run failed or the scan couldn’t start. |
ping has the automation and nothing else: finding, repo_url, and run are null.
Delivery status
For an automation with no action, the Run history tab lists each finding the automation matched and how each webhook delivery went:
| Status | What it means |
|---|---|
| Queued | The delivery is waiting to be sent. |
| Delivered | Your endpoint answered with a 2xx status. |
| Retrying | The last attempt failed, and Hacktron will try again. The status shows the answer and the attempt number. |
| Failed after 10 attempts | Every attempt failed. |
| Failed: could not be sent | Hacktron couldn’t queue the delivery. |
| Stopped | Your endpoint answered 410 Gone. |
| Not sent: the webhook was removed | The webhook was removed before the delivery was sent. |
Members who aren’t Admins see only the endpoint’s host, not its full URL.
Change the signing secret
A webhook keeps its signing secret until you remove it. To get a new secret, for example after the old one leaks:
- Remove the webhook, add a new one with the same URL, and select Save changes.
- Copy the new webhook’s signing secret, and update your endpoint with it.
Deliveries queued for the removed webhook aren’t sent.