Skip to main content

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.

Webhook platforms, the URL pattern each is detected by, and the payload shape it receives
PlatformURL patternPayload shape
Discorddiscord.com/api/webhooks/* or discordapp.com/api/webhooks/*Rich embeds with colour-coded severity
Slackhooks.slack.com/*Block Kit with section fields
GenericAny other HTTPS endpointPlain 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.

GET
/webhooks

List Webhooks

Your own webhooks plus any assigned to a team you belong to. All team roles can read them.

Response
200 OK

JSON
{
  "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

401
Unauthorized
POST
/webhooks

Create Webhook

Create a new webhook. URL must be a public HTTPS endpoint. Type is auto-detected if not specified.

Request Body

JSON
{
  "url": "https://discord.com/api/webhooks/xxx/yyy",
  "name": "Security Alerts",
  "type": "auto"
}

Response
200 OK

JSON
{
  "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"
}
Returns 201, not 200. Per-user limit is set by your plan: 1 on Free, 1 on Core Supporter, 5 on Pro Supporter, unlimited on Elite Supporter
URL must be HTTPS (no localhost, no private IPs, no link-local)
type defaults to auto-detect; allowed values are auto | discord | slack | generic. Only the detected value is stored.
secret is returned on this response and, if you ever have to replace it, on POST /webhooks/{id}/rotate-secret. Nothing else returns it, so save it now: it signs every delivery.

Error Responses

400
Invalid URL, SSRF blocked, or plan limit reached
401
Unauthorized
403
Webhooks are disabled on this deployment
PATCH
/webhooks

Test 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

JSON
{
  "id": 1
}

Response
200 OK

JSON
{
  "success": true,
  "message": "Test webhook sent successfully"
}
The test delivery is NOT signed and carries no User-Agent: it goes out with Content-Type: application/json only. A consumer that rejects unsigned payloads will fail the Test button even though real deliveries would verify fine. Allow the test through, or verify against a real scan instead.

Error Responses

400
Missing id, the target is now SSRF-blocked, or your endpoint returned a non-2xx status
401
Unauthorized
403
You can read this webhook but have no write access to it
404
Webhook not found, or no access
PATCH
/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

JSON
{
  "active": false
}

Response
200 OK

JSON
{
  "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"
}
Send { active: true|false } alone to pause or resume without touching the URL
url, name, type and teamId are all optional and independent -- send only what changed
A new url goes through the same HTTPS + SSRF checks as creation
The owner, or a team co-member with write access, may edit. A read-only co-member gets 403 because they legitimately know it exists; anyone with no access at all gets 404. Changing teamId is owner-only.

Error Responses

400
Nothing to update, or the new URL was rejected
401
Unauthorized
403
Read access but not write access, or not the owner when changing teamId
404
Webhook not found, or no access
DELETE
/webhooks

Delete Webhook

Permanently delete a webhook.

Request Body

JSON
{
  "id": 1
}

Response
200 OK

JSON
{
  "success": true
}
An id that does not exist returns { success: true } with a 200, not a 404: there is nothing to delete and nothing to reveal about whose id it might be.

Error Responses

401
Unauthorized
403
No write access to this webhook

Events

Webhook events, when each fires, and what its payload carries
EventFires whenPayload carries
scan.completedEvery scan that finishes and is persistedSeverity counts, duration, and what did not finish
scan.regressedA scan turns up a critical or high finding that was not in the previous scan of the same targetThe 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

JSON
{
  "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

JSON
{
  "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

JSON
{
  "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

JSON
{
  "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 no User-Agent. Lost or leaked the secret? Call POST /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

  1. In Discord: Server Settings → Integrations → Webhooks → New Webhook. Copy the URL.
  2. Log in to VulnRadar, open /profile → Webhooks → Add Webhook.
  3. Paste the URL and an optional label. Type is auto-detected.
  4. Click Test. A test payload posts to Discord; you should see a colored embed within a few seconds.

Local development: receive on webhook.site

  1. Open https://webhook.site and copy the URL.
  2. Paste it as a webhook in VulnRadar. It is detected as generic.
  3. Run any scan. The full JSON payload appears at the top of yourwebhook.site page.
Webhooks: Get Scan Results Over HTTP | VulnRadar