OpenAI is partnering with Hacktron to find vulnerabilities in its systems. Read the announcement.

Skip to content Hacktron Sign in [S]
Hacktron Sign in [S] Customers Docs Contact Sign in

Webhooks

5 min
, View, ChatGPT, Claude, Perplexity

Copy page

Webhooks

View MarkdownOpen in ChatGPTOpen in ClaudeOpen in Perplexity

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.

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

app.py
import os
from flask import Flask, request
from 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 "", 204
Other languages
  1. Join the webhook-id header, the webhook-timestamp header, and the raw body with full stops: {webhook-id}.{webhook-timestamp}.{body}.
  2. Remove whsec_ from the start of the secret and base64-decode the rest. The result is the signing key.
  3. Compute the HMAC-SHA256 of the joined string with that key, and base64-encode it.
  4. webhook-signature is a list of signatures separated by spaces, each written v1,<signature>. Accept the delivery if yours matches one of them, using a constant-time comparison.
  5. Reject the delivery if webhook-timestamp is 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-id to skip a delivery you’ve already handled, and the body’s timestamp to 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.

automation.finding.matched
{
"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:

  1. Remove the webhook, add a new one with the same URL, and select Save changes.
  2. Copy the new webhook’s signing secret, and update your endpoint with it.

Deliveries queued for the removed webhook aren’t sent.

Automations Remediation Scheduled whitebox scans
[↓] [↑] [enter] to visit
Menu
[M]
Next in menu
[J]
Previous in menu
[K]
Find
[F]
Ask
[A]
Sign in
[S]
Copy page
[C]
Listen
[L]
Justification
[R]
Language
[G]
Dark mode
[D]
High contrast
[H]
Shortcuts
[I]
Close
[Esc]