---
title: Webhooks
description: Send automation events to your own endpoint and verify them with
  the signing secret.
url: https://www.hacktron.ai/docs/platform/automations/webhooks
---

# Webhooks

A webhook notifier sends an [automation's](/docs/platform/automations) 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](https://www.standardwebhooks.com) 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

::::steps

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

::::

:::tip[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](/docs/platform/automations/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.

::::tabs

:::tab[Node.js]

Install the library with `npm install standardwebhooks`.

```js title="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)
```

:::

:::tab[Python]

Install the library with `pip install standardwebhooks`.

```python title="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
```

:::

:::tab[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](/docs/platform/automations/remediation) run for a matching finding. |
| `automation.run.finished` | That remediation run finished. |
| `automation.scan.finished` | A [scheduled whitebox scan](/docs/platform/automations/scheduled-whitebox-scans) 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.

```json title="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.

## Related docs

:::tiles
- [Automations](/docs/platform/automations): Run actions and send notifications on triggers.
- [Remediation](/docs/platform/automations/remediation): Receive fixes as pull requests.
- [Scheduled whitebox scans](/docs/platform/automations/scheduled-whitebox-scans): Repeat scans on a schedule.
:::
