Skip to content

Webhooks

A webhook sends your organization’s finding events to a URL you choose, as they happen: a new finding in a release, a finding that becomes known exploited, a finding that goes away, and the first check of a newly uploaded release; and, if you choose, each proposal an agent files for review. Your own tools receive them as HTTPS requests in the Standard Webhooks format, signed, so a receiver can check that a request comes from Affectra. The same endpoints can also post a message to a Slack, Microsoft Teams, Google Chat or Mattermost channel, or start a GitHub Actions workflow; see Formats.

Admins and owners manage webhooks under Webhooks in the navigation. An organization has at most 10 endpoints.

Every request carries release names and vulnerability IDs. Anyone who can read what arrives at the URL learns what your products are vulnerable to. Add only endpoints you control, on a host you trust. A request contains no advisory text and no list of your components.

The URL, the signing secret and the extra header’s value are stored encrypted. Only the part of Affectra that sends webhooks can read them. After you save an endpoint, the app shows only the start of the URL and the last four characters of its path, and never the secret or the header value again.

  1. Open Webhooks.
  2. Choose the Format: Standard Webhooks for your own receivers, or one of the formats in Formats. You can’t change it later.
  3. Enter the URL. It must use https, name a host (not an IP address), and use port 443 or 8443. The host must resolve to public addresses only. Some formats accept only their service’s hosts.
  4. Optionally add a Description, such as Jira automation, and choose the Language of chat messages.
  5. Under Events, choose what to send. A new Standard Webhooks or GitHub endpoint gets every finding event and first checks; a new Slack, Teams or Google Chat endpoint gets known exploited findings and first checks. Proposal filed is never on by default: select it for the endpoints that should hear about new agent proposals.
  6. If your receiver wants a token in a header, add an Extra header: Authorization or a name that starts with X-. A GitHub endpoint needs one.
  7. Select Add endpoint, and copy the signing secret that Affectra shows. It starts with whsec_. You can’t see it again; if you lose it, make a new one with New secret.

Select an endpoint in the list to open its panel. It shows the format, the status and the extra header’s name, and has the actions Send test event, New secret and Delete. Below them, Deliveries is the endpoint’s delivery log and Settings changes its description, events and language, gives it a new URL or header value, or turns it off.

Select Send test event in the panel to check the setup. Affectra sends an event of type webhook.test to that endpoint only, and it shows under Deliveries within seconds.

The format decides what the request body looks like and which hosts the URL may name. Affectra checks the host when you save the endpoint and again before each request. Every format carries the signature headers, and receivers that don’t check them can ignore them.

Format Body Allowed hosts Requests
Standard Webhooks The event as JSON Any public host One per event
GitHub repository_dispatch {"event_type": "<type>", "client_payload": <the event>} api.github.com, path /repos/OWNER/REPO/dispatches One per event
Slack Block Kit blocks and a text with the whole message Any public host, hooks.slack.com for Slack One message per run
Microsoft Teams An Adaptive Card for a Workflows webhook Subdomains of logic.azure.com and api.powerplatform.com One message per run
Google Chat cardsV2 and a text chat.googleapis.com One message per run

Chat messages (Slack, Teams, Google Chat, Mattermost) are batched like email. Affectra sends in runs, at least every 30 seconds and as soon as new events arrive, and everything an endpoint is due in one run goes into one message. A message lists up to 10 changes: known exploited findings first, then new findings by severity and CVSS score, first checks of releases, proposals agents filed, and resolved findings last. A proposal names what it would write (a VEX statement for a vulnerability in a release, a CPE mapping or a unit link), the agent that filed it, and a link to the proposal in Affectra. When there are more, it says “and N more” with a link to your releases in Affectra. Each item names the release (product and version), the CVE (or the advisory ID for an advisory without a CVE), the severity, the CISA due date for a known exploited finding, and a link to the release’s vulnerabilities in Affectra. A message never contains advisory text. Affectra sends at most one message a second to an endpoint, and a message that fails is tried again with all its events together, on the schedule in Retries.

Chat messages are in the language you choose for the endpoint. Product, release and organization names come from your own data and show as plain text: a name such as <!channel> or @here doesn’t ping anyone, and none of them becomes a link. Everyone who can read the channel sees the messages, guests included. Pick a channel whose members may know what your products are vulnerable to.

Send test event posts a short Test message from Affectra in each format.

  1. In Slack, create an app for your workspace and turn on Incoming Webhooks. Add a webhook to the channel that should get the messages, and copy its URL (it starts with https://hooks.slack.com/services/).
  2. In Affectra, choose the format Slack (also Mattermost) and enter the URL.
  3. Select Add endpoint. Open the endpoint and select Send test event.

Microsoft is retiring the Office 365 connectors in Teams, so Affectra accepts only Workflows URLs.

  1. In Teams, open the channel’s … menu, choose Workflows, and pick the template Post to a channel when a webhook request is received. Choose the team and channel, and finish the wizard.
  2. Copy the workflow’s URL. It looks like https://prod-00.westeurope.logic.azure.com:443/workflows/….
  3. In Affectra, choose the format Microsoft Teams (Workflows), enter the URL, and select Add endpoint. Open the endpoint and select Send test event.

Affectra sends an Adaptive Card 1.4 in a message attachment, which this template posts to the channel. A URL that isn’t a subdomain of logic.azure.com or api.powerplatform.com is refused.

  1. In the Google Chat space, open the space’s name and choose Apps & integrations, then Webhooks. Add a webhook with a name such as Affectra and copy its URL (https://chat.googleapis.com/v1/spaces/…).
  2. In Affectra, choose Google Chat, enter the URL, and select Add endpoint. Open the endpoint and select Send test event.

Mattermost reads the Slack format. Affectra’s text carries the whole message, because Mattermost shows only text and ignores blocks.

  1. In Mattermost, open Integrations, then Incoming Webhooks, and add one for the channel. Copy its URL.
  2. In Affectra, choose Slack (also Mattermost), enter the URL, and select Add endpoint. Open the endpoint and select Send test event.

A self-hosted Mattermost on a private network needs a self-hosted Affectra with notifications.webhooks.allowPrivateNetworks; see Private networks.

The format GitHub repository_dispatch starts a workflow in one repository for each event.

  1. Create a fine-grained personal access token for that repository with the Contents permission set to Read and write. Dispatching an event needs nothing else.
  2. In Affectra, choose GitHub repository_dispatch and enter https://api.github.com/repos/OWNER/REPO/dispatches. Under Authorization header, enter Bearer followed by the token. The header is required.
  3. Add a workflow on the repository’s default branch that listens for the event types you chose:
name: Affectra finding
on:
repository_dispatch:
types: [finding.known_exploited]
jobs:
issue:
runs-on: ubuntu-latest
permissions:
issues: write
steps:
- name: Open an issue
env:
GH_TOKEN: ${{ github.token }}
VULN: ${{ github.event.client_payload.data.group.key }}
PRODUCT: ${{ github.event.client_payload.data.release.product }}
RELEASE: ${{ github.event.client_payload.data.release.name }}
SEVERITY: ${{ github.event.client_payload.data.severity }}
DUE: ${{ github.event.client_payload.data.kev_due_date }}
LINK: ${{ github.event.client_payload.data.url }}
run: |
gh issue create --repo "$GITHUB_REPOSITORY" \
--title "$VULN in $PRODUCT $RELEASE" \
--body "Severity: $SEVERITY. CISA due date: $DUE. $LINK"

Pass the payload to the script through env, as above, and not as ${{ … }} inside run: product and release names are data from your organization, and the shell would run what a name contains.

The request body is {"event_type": "finding.known_exploited", "client_payload": { … }}, where client_payload is the event from The request. GitHub answers 204, which counts as delivered. Affectra sends the headers Accept: application/vnd.github+json and X-GitHub-Api-Version: 2022-11-28. The workflow runs when GitHub receives the request, so a failed run doesn’t show in Affectra’s delivery log.

Type Sent when
finding.new A release has a CVE it didn’t have before.
finding.known_exploited A finding’s CVE is known exploited: CISA added it to its Known Exploited Vulnerabilities catalog (KEV), or a new finding is already in it.
finding.resolved No advisory reports the CVE in the release any more: a feed corrected its data, a package mapping was removed, or a new SBOM replaced the release’s components.
release.matched Affectra checked a newly uploaded release for the first time. One event with counts, instead of a finding.new for each finding.
proposal.filed An agent filed a proposal for a person to review, over the API or MCP. Only endpoints that select it get it; it’s never sent by email.
org.feed_subscription_changed An admin turned a vulnerability feed on or off for your organization. Only endpoints that select it get it; it’s never sent by email.
webhook.test You selected Send test event. Only that endpoint gets it.

Affectra sends no finding.new or finding.known_exploited for a finding whose VEX statement says not_affected or fixed. A new or changed VEX statement sends no event.

NVD, GitHub, a Linux distribution and a vendor often each publish an advisory for the same CVE. Affectra groups them, as the Vulnerabilities tab does, and sends finding events for the group: one for each CVE in a release.

  • finding.new comes once, when the first advisory for the CVE matches the release. An advisory for the same CVE that matches later, such as a GitHub advisory after the NVD record, sends nothing.
  • finding.known_exploited comes once for each CVE in a release, however many advisories report it.
  • finding.resolved comes when the last advisory for the CVE no longer matches. While another advisory still reports it, the finding stays open.
  • release.matched counts CVEs, not advisories.
  • An advisory that names two CVEs, such as a Debian advisory, is in two groups and can send two events.
  • An advisory without a CVE is a group of its own, unless it is an alias of another advisory without a CVE, such as a Go advisory and the GitHub advisory it names. Then they are one group.
  • Advisories that disagree about a component’s version send no event of their own; data.group.conflict shows it in the next event.

The same events, except webhook.test, are in the events feed, where AI agents (the MCP tool list_events) and scripts fetch them instead of receiving them.

Affectra sends a POST with the event as JSON:

{
"id": "evt_6f1c2e8a-3b0d-4f53-9a41-1d2c7b5e9f10",
"type": "finding.known_exploited",
"occurred_at": "2026-11-11T09:12:03Z",
"org": "acme",
"data": {
"release": { "id": "0c5f1d6e-…", "product": "Gateway X", "name": "4.2.1" },
"vulnerability": { "source": "osv", "id": "GHSA-8489-44mv-ggj8", "cves": ["CVE-2026-1234"] },
"group": {
"key": "CVE-2026-1234",
"cve": "CVE-2026-1234",
"advisories": [
{ "source": "osv", "id": "GHSA-8489-44mv-ggj8" },
{ "source": "nvd", "id": "CVE-2026-1234" }
],
"conflict": false
},
"severity": "high",
"cvss_score": 8.1,
"kev_due_date": "2026-12-02",
"url": "https://app.affectra.eu/#/release/0c5f1d6e-…/vulnerabilities"
}
}

data.vulnerability is the advisory the event is about: for a new or known exploited finding, the one Affectra ranks first in the group (a vendor’s CSAF advisory, then other CSAF advisories, then OSV, then NVD); for a resolved one, the advisory the earlier event named. data.group is the finding group:

Field
key The CVE, or for advisories without a CVE the source and the smallest ID among the advisory and its aliases, such as osv:GHSA-xxxx-xxxx-xxxx. Use it to find the event’s issue or ticket again: it stays the same for the CVE in that release. The key of a group without a CVE can change when its advisories’ aliases change, when an advisory gains a CVE, or when one of its advisories is removed while others remain. A group can also split: when the advisory its key names gains a CVE, that advisory joins the CVE’s group and the others get a key of their own. Affectra sends no event for any of these changes, and later events use the new keys.
cve The CVE, or null for an advisory without one.
advisories Every advisory in the group, the first being data.vulnerability. Empty in finding.resolved, when none is left.
conflict true when one advisory says a component of the release is affected and another with the same CVE says its version is not.

severity and cvss_score are the highest of the group’s advisories. A finding.resolved event also has data.cause: match_removed or sbom_replaced. A release.matched event has data.findings, the open findings by severity (critical, high, medium, low, unknown), and data.known_exploited, how many of them are known exploited.

A proposal.filed event names the proposal and what it’s about, never its evidence or the agent’s explanation:

{
"id": "evt_2b7d4c1e-9a6f-4e08-8c3d-5f1a0b9e7d24",
"type": "proposal.filed",
"occurred_at": "2026-11-12T14:03:27Z",
"org": "acme",
"data": {
"proposal": { "id": "019a7f3c-…", "kind": "vex_statement" },
"release": { "id": "0c5f1d6e-…", "product": "Gateway X", "name": "4.2.1" },
"vulnerability": { "source": "nvd", "id": "CVE-2026-1234" },
"agent": "triage-bot",
"url": "https://app.affectra.eu/#/proposals/019a7f3c-…"
}
}

data.proposal.kind is vex_statement, purl_cpe_mapping or unit_release_link. data.release is there when the proposal is about a release (a VEX statement or a unit link), and data.vulnerability for a VEX statement; its source is the feed that has the ID, and is left out when no feed has it. data.agent is the name of the API key or OAuth client that filed it, as the Proposals page shows it; it’s left out for a person’s own token. Fetch the full proposal, with its evidence, from GET /v1/orgs/{org}/proposals/{id}.

An org.feed_subscription_changed event names the feed, its new state and who changed it:

{
"id": "evt_7c2e9b40-1d3a-4f6e-8b52-0a9d4c3e2f18",
"type": "org.feed_subscription_changed",
"occurred_at": "2026-11-14T10:21:05Z",
"org": "acme",
"data": {
"feed": "csaf:siemens",
"subscribed": false,
"changed_by": "8f14e45f-ceea-467a-9575-6f1b2a3c4d5e",
"url": "https://app.affectra.eu/#/settings"
}
}

data.feed is nvd or csaf: and the provider, as GET /v1/orgs/{org}/feeds lists it. data.changed_by is the ID of the member who changed it, or api-key. Asking for the state a feed is already in sends nothing.

The headers:

Header Value
webhook-id The event’s ID, the same as id in the body.
webhook-timestamp When the request was signed, in seconds since 1970 (Unix time).
webhook-signature v1, and the signature. After a secret rotation, two of them, separated by a space.
Content-Type application/json
User-Agent Affectra-Webhooks/1

Your extra header, if you set one, comes with every request.

Answer with any 2xx status within 10 seconds. Affectra reads at most 4 KiB of your answer and ignores it. It doesn’t follow redirects: a 3xx answer counts as a failure.

The signature is an HMAC-SHA256 over the webhook-id, the webhook-timestamp and the raw body, joined by dots, keyed with the part of your secret after whsec_ (base64-decoded). The Standard Webhooks libraries check it and refuse requests older than 5 minutes, which stops replays. Check the raw body exactly as it arrived, before any JSON parsing.

Go, with github.com/standard-webhooks/standard-webhooks/libraries/go:

wh, err := standardwebhooks.NewWebhook(os.Getenv("AFFECTRA_WEBHOOK_SECRET"))
if err != nil {
log.Fatal(err)
}
http.HandleFunc("POST /hooks/affectra", func(w http.ResponseWriter, r *http.Request) {
body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
if err != nil {
http.Error(w, "cannot read the body", http.StatusBadRequest)
return
}
if err := wh.Verify(body, r.Header); err != nil {
http.Error(w, "invalid signature", http.StatusUnauthorized)
return
}
// Handle the event (json.Unmarshal(body, &event)), then answer 2xx.
w.WriteHeader(http.StatusNoContent)
})

Python, with the standardwebhooks package and Flask:

import os
from flask import Flask, request
from standardwebhooks.webhooks import Webhook
app = Flask(__name__)
wh = Webhook(os.environ["AFFECTRA_WEBHOOK_SECRET"])
@app.post("/hooks/affectra")
def affectra():
try:
event = wh.verify(request.get_data(), dict(request.headers))
except Exception:
return "invalid signature", 401
# Handle event (a dict), then answer 2xx.
return "", 204

Node.js, with the standardwebhooks package and Express:

import express from "express";
import { Webhook } from "standardwebhooks";
const app = express();
const wh = new Webhook(process.env.AFFECTRA_WEBHOOK_SECRET);
app.post("/hooks/affectra", express.raw({ type: "application/json" }), (req, res) => {
let event;
try {
event = wh.verify(req.body.toString("utf8"), req.headers);
} catch {
return res.sendStatus(401);
}
// Handle event, then answer 2xx.
res.sendStatus(204);
});

Affectra sends each event at least once, not exactly once: a retry after a lost answer, or a delivery you send again, repeats an event. Each repeat has the same webhook-id, so keep the IDs you handled for a few days and skip one you’ve seen.

Requests can arrive out of order, because Affectra sends up to 4 at a time to an endpoint and retries failed ones later. Sort by occurred_at when the order matters.

Retries and when an endpoint is turned off

Section titled “Retries and when an endpoint is turned off”

A request that doesn’t get a 2xx answer within 10 seconds is tried again after 30 seconds, 2 minutes, 10 minutes, 1 hour, 4 hours, 12 hours and 24 hours: 8 attempts over about two days. After that, the delivery is marked failed.

Affectra turns an endpoint off:

  • at once, when it answers 410 Gone. Answer 410 to tell Affectra to stop.
  • when every attempt to it failed for 3 days.

Nothing is sent to an endpoint while it’s off, and deliveries still waiting are skipped. The admin who created the endpoint gets an email saying so, or the organization’s owners, if that admin is no longer an admin or owner. This email is about your organization’s settings, so it’s sent whether or not you turned on finding emails.

Once the receiver works again, open the endpoint on the Webhooks page and select Turn on.

At most 10 requests a second and 4 at a time go to one endpoint; a chat endpoint gets at most one message a second.

Open an endpoint and look under Deliveries to see what Affectra sent to it in the last 30 days, newest first: the event, whether it was delivered, is still pending, failed or was skipped, how many attempts it took, your receiver’s last status, and why the last attempt failed. The log never shows the URL.

Send again sends a delivery again now. A pending delivery is tried at once. Any other gets a new delivery of the same event, with the same webhook-id and a new series of retries.

Open the endpoint and select New secret to get a new signing secret. The panel shows it once. For 24 hours, Affectra signs every request with both the new and the old secret, so the webhook-signature header has two signatures. The Standard Webhooks libraries accept a request when one of them matches. Update your receiver within that time.

Jira Automation can create an issue for each event with its Incoming webhook trigger. It checks a token header instead of the signature.

  1. In Jira, open Project settings, then Automation, and create a rule with the trigger Incoming webhook. Jira shows the webhook’s URL and a secret.
  2. Add the condition If: smart values condition: {{webhookData.type}} equals finding.known_exploited. Add finding.new with a second rule, or an Or condition.
  3. Add the action Create issue with, for example:
    • Summary: {{webhookData.data.vulnerability.id}} in {{webhookData.data.release.product}} {{webhookData.data.release.name}}
    • Description: Severity {{webhookData.data.severity}}. {{webhookData.data.url}}
  4. Turn the rule on.
  5. In Affectra, add an endpoint with Jira’s URL. Under Extra header, enter the name X-Automation-Webhook-Token and Jira’s secret as the value. Under Events, choose the types the rule handles.
  6. Open the endpoint and select Send test event. The rule’s audit log in Jira shows that it ran; the condition skips the test event.

A retry or a delivery you send again repeats an event, and this rule then creates a second issue. To avoid that, add a Lookup issues action for the vulnerability ID and the release before Create issue, and create the issue only when the lookup finds none.

The hosted service sends webhooks only to public addresses. When Affectra connects, it checks the address the host resolves to then, and refuses loopback, link-local, private and reserved addresses, whatever the host resolved to when you saved the endpoint. A self-hosted installation can allow private networks, for example for an internal Jira, with the Helm value notifications.webhooks.allowPrivateNetworks. Loopback and link-local addresses, including cloud metadata services, stay refused.