Integrations
Webhooks
Receive real-time notifications when scans complete. VulnRadar auto-detects the platform type from the URL and formats the payload accordingly.
- Max per user, by plan
- 1-∞
- Platform types
- 3
- Required
- HTTPS
Overview
Webhooks fire after every successful scan triggered by a session or an API key. Most scans run as background jobs, so delivery happens when the job actually finishes rather than when the request that started it returned; an authenticated scan and a GitHub repo scan run inline, and fire as they finish. Each delivery is signed (see Security below) and re-checks the destination URL against the SSRF rules again at delivery time, not just when you registered it. A delivery that fails (network error, timeout, or a non-2xx response) gets exactly one retry a few seconds later; if that also fails, the attempt is logged and, if you have the notification enabled, you get an email. The per-user cap is set by your plan, not a flat number: 1 on Free, 1 on Core Supporter, 5 on Pro Supporter, unlimited on Elite Supporter. Free accounts do get a webhook: the step up you pay for is 1 to 5 at Pro Supporter.
Every kind of scan fires them: a single-URL scan, a crawl (what --crawl runs in the CLI and the GitHub Action), a bulk run, an authenticated scan, and a GitHub repo scan. Only one of those used to, so if you registered a webhook and never saw a delivery from a crawl or an authenticated scan, that is why.
A webhook can also be assigned to a team. A team-assigned webhook is visible to every co-member, editable by those with write access, and fires on a teammate's scans as well as its creator's.
Supported Platforms
VulnRadar detects the platform by matching the URL pattern. Override with the type body field if needed.
| Platform | URL pattern | Payload shape |
|---|---|---|
| Discord | discord.com/api/webhooks/* or discordapp.com/api/webhooks/* | Rich embeds with colour-coded severity |
| Slack | hooks.slack.com/* | Block Kit with section fields |
| Generic | Any other HTTPS endpoint | Plain JSON { event, data } |
Generic is the row most integrations end up on: anything that is not Discord or Slack gets the plain { event, data } body, which is the one documented in Webhook Payloads below.
API Endpoints
Manage webhooks through these session-authenticated endpoints (the /api/v3/webhooks family requires a logged-in user; API keys are not accepted). Two more exist and are documented in full on the API reference: POST /webhooks/{id}/rotate-secret (issue a new signing secret in place, owner only) and GET /webhooks/{id}/deliveries (the 50 most recent delivery attempts with their status). Both are also on the Webhooks page, as the rotate and history buttons on each row. The same rows carry the team picker for teamId, so handing a webhook to a team no longer needs a PATCH of your own.
/webhooksList Webhooks
Your own webhooks plus any assigned to a team you belong to. All team roles can read them.
Response 200 OK
{
"webhooks": [
{
"id": 1,
"url": "https://discord.com/api/webhooks/xxx/yyy",
"name": "Security Alerts",
"type": "discord",
"active": true,
"created_at": "2026-03-10T15:30:00.000Z"
}
]
}Error Responses
/webhooksCreate Webhook
Create a new webhook. URL must be a public HTTPS endpoint. Type is auto-detected if not specified.
Request Body
{
"url": "https://discord.com/api/webhooks/xxx/yyy",
"name": "Security Alerts",
"type": "auto"
}Response 200 OK
{
"id": 1,
"url": "https://discord.com/api/webhooks/xxx/yyy",
"name": "Security Alerts",
"type": "discord",
"active": true,
"created_at": "2026-03-10T15:30:00.000Z",
"secret": "b6f2e1...9c4a"
}Error Responses
/webhooksTest Webhook
Sends a test payload to verify the webhook is reachable and accepts the format. A 200 means your endpoint answered with a 2xx; the response does not relay your endpoint's exact status code.
Request Body
{
"id": 1
}Response 200 OK
{
"success": true,
"message": "Test webhook sent successfully"
}Error Responses
/webhooks/{id}Edit or Pause Webhook
Update a webhook in place: pause/resume delivery, or change its name, URL, and type. Only fields you send are changed.
Request Body
{
"active": false
}Response 200 OK
{
"id": 1,
"url": "https://discord.com/api/webhooks/xxx/yyy",
"name": "Security Alerts",
"type": "discord",
"active": false,
"created_at": "2026-03-10T15:30:00.000Z"
}Error Responses
/webhooksDelete Webhook
Permanently delete a webhook.
Request Body
{
"id": 1
}Response 200 OK
{
"success": true
}Error Responses
Events
| Event | Fires when | Payload carries |
|---|---|---|
| scan.completed | Every scan that finishes and is persisted | Severity counts, duration, and what did not finish |
| scan.regressed | A scan turns up a critical or high finding that was not in the previous scan of the same target | The new findings themselves, plus what is outstanding |
Both go to the same registered webhooks, and scan.regressed is sent after that scan's scan.completed, never instead of it. It is the same diff the critical-findings email is built from: a finding you have marked a false positive, accepted the risk of, or decided not to fix does not count as new, so a persistent finding on an hourly schedule does not re-alert every run.
It exists because scan.completed carries counts and not findings, so routing an alert to a person meant a second API call to work out what actually changed. scan.regressed carries the findings inline, which is what makes a Slack or Discord alert diff-driven rather than count-driven.
Webhook Payloads
Each platform receives a tailored payload. The summary object is the same in all three: critical, high, medium, low, info, total.
What identifies the target depends on what was scanned. A web scan sends url (and normalizedUrl, the same value, kept for consumers written against the older payload). A GitHub repo scan has no URL, so it sends repository and no url key at all rather than a URL-shaped string that is not one. Branch on whichever key is present.
Discord
{
"embeds": [
{
"title": "VulnRadar Scan Complete",
"description": "Scan finished for **https://example.com**",
"color": 15158332,
"fields": [
{ "name": "Critical", "value": "1", "inline": true },
{ "name": "High", "value": "2", "inline": true },
{ "name": "Medium", "value": "1", "inline": true },
{ "name": "Low", "value": "1", "inline": true },
{ "name": "Info", "value": "0", "inline": true },
{ "name": "Total Issues", "value": "5", "inline": true },
{ "name": "Duration", "value": "1.4s", "inline": true }
],
"footer": { "text": "VulnRadar Security Scanner" },
"timestamp": "2026-03-10T15:30:00.000Z"
}
]
}Embed color follows the scan’s safety verdict, the same safe/caution/unsafe tier the badge and the host page use, not a raw severity count: 0x22c55e (green, safe), 0xeab308 (yellow, caution), 0xef4444 (red, unsafe). A count-based rule cannot tell an exploitable high from a hardening one like a missing HSTS header, so it used to paint scans red that the scorer calls safe.
Slack
{
"blocks": [
{
"type": "header",
"text": {
"type": "plain_text",
"text": "VulnRadar Scan Complete"
}
},
{
"type": "section",
"text": { "type": "mrkdwn", "text": "*URL:* https://example.com" }
},
{
"type": "section",
"fields": [
{ "type": "mrkdwn", "text": "*Critical:* 1" },
{ "type": "mrkdwn", "text": "*High:* 2" },
{ "type": "mrkdwn", "text": "*Medium:* 1" },
{ "type": "mrkdwn", "text": "*Low:* 1" },
{ "type": "mrkdwn", "text": "*Total:* 5" },
{ "type": "mrkdwn", "text": "*Duration:* 1.4s" }
]
},
{
"type": "context",
"elements": [
{ "type": "mrkdwn", "text": "Sent by VulnRadar Security Scanner" }
]
}
]
}Generic: scan.completed
{
"event": "scan.completed",
"data": {
"url": "https://example.com",
"normalizedUrl": "https://example.com",
"scan_id": 4821,
"summary": {
"critical": 1, "high": 2, "medium": 1, "low": 1, "info": 0, "total": 5
},
"findings_count": 5,
"duration": 1423,
"scanned_at": "2026-03-10T15:30:00.000Z",
"incomplete": ["dns", "tls"]
}
}incomplete is present only when part of the scan did not finish, and it is the difference between “we found nothing” and “we could not finish looking”. An area listed there was not checked, so treat a findings_count of 0 alongside it as unknown, not clean. When every branch ran the key is absent entirely, so a consumer that only tests for the key can tell the two apart. The Discord embed carries the same fact as a Coverage field and Slack as an extra section, since neither format has a key to read.
Delivered with Content-Type: application/json, User-Agent: VulnRadar-Webhook/1.0, and (if the webhook has a secret) an X-VulnRadar-Signature header -- see Security below.
Generic: scan.regressed
{
"event": "scan.regressed",
"data": {
"url": "https://example.com",
"normalizedUrl": "https://example.com",
"scan_id": 4821,
"scanned_at": "2026-03-10T15:30:00.000Z",
"new_findings_count": 1,
"outstanding_findings_count": 2,
"new_findings": [
{
"id": "exposed-db-credentials--a1b2c3",
"title": "Database credentials exposed in JavaScript bundle",
"severity": "critical",
"category": "secrets-extended"
}
],
"outstanding_findings": [
{
"id": "csp-unsafe-inline--a1b2c3",
"title": "Content-Security-Policy allows unsafe-inline",
"severity": "high",
"category": "headers"
}
]
}
}new_findings is what changed since the previous scan of this target: critical and high only, with anything you have already triaged removed. outstanding_findings is what was already there and still is. Finding id is stable across scans of the same URL, so it works as a deduplication key in your own alerting. Discord and Slack receive the same diff as a formatted message listing the first ten new findings.
Security
- HTTPS only: the create endpoint rejects
http://URLs. - SSRF protection: webhooks cannot target localhost,
127.0.0.1,0.0.0.0,[::1],169.254.169.254(AWS metadata),metadata.google.internal,*.local, private IP ranges (10/8, 172.16/12, 192.168/16), or any hostname that resolves to them. This is checked again before every delivery attempt, not just at registration or edit time, in case DNS or routing changed in between. - Signed payloads: each webhook gets a secret at creation time, returned once in the create response and never shown again. Every delivery includes
X-VulnRadar-Signature: sha256=<hex>, an HMAC-SHA256 of the exact request body using that secret -- compute the same HMAC on your end and compare to verify a payload actually came from VulnRadar. The one exception is the Test button, whose delivery is unsigned and carries noUser-Agent. Lost or leaked the secret? CallPOST /api/v3/webhooks/{id}/rotate-secret(owner only) for a new one on the same row: the id and the URL survive, so your consumer’s configuration does not have to change. Every signature it is currently verifying stops matching the moment that returns, so deploy the new secret first. - Timeout: 10 seconds per delivery attempt (
AbortSignal.timeout(10000)). - One retry, then logged: a network error, an SSRF block, or a non-2xx response gets exactly one retry a few seconds later. Every attempt (including the retry) is recorded with its status. If both attempts fail and you have the notification enabled, you get an email -- this is still best-effort delivery, not a guaranteed queue, so build idempotency into your consumer regardless.
- Per-user cap, by plan: 1 on Free, 1 on Core Supporter, 5 on Pro Supporter, unlimited on Elite Supporter. Delete or upgrade to add more.
- Session-only API: Bearer keys cannot manage webhooks: only logged-in users can create, list, edit, pause, test, and delete them. Every write is scoped to webhooks the caller owns or has team write access to; rotating the secret and reassigning the team are owner-only.
Integration Examples
Creating a Discord webhook
- In Discord: Server Settings → Integrations → Webhooks → New Webhook. Copy the URL.
- Log in to VulnRadar, open
/profile→ Webhooks → Add Webhook. - Paste the URL and an optional label. Type is auto-detected.
- Click Test. A test payload posts to Discord; you should see a colored embed within a few seconds.
Local development: receive on webhook.site
- Open
https://webhook.siteand copy the URL. - Paste it as a webhook in VulnRadar. It is detected as
generic. - Run any scan. The full JSON payload appears at the top of your
webhook.sitepage.