Events and payloads
All docs
Every alert is an event. This page lists all event types and what they contain. Email and webhooks carry the same events, webhooks as JSON.
Event types
| Type | When | On by default |
|---|---|---|
vulnerability.created |
A new vulnerability affects software you watch | Yes |
vulnerability.updated |
The title, description, severity, CVE, CWE, affected versions or the fix changed | Yes |
vulnerability.deleted |
The vulnerability was withdrawn by its source | Yes |
vulnerability.patched |
The source marks the vulnerability as fixed | No |
patch.released |
The fixed version can actually be downloaded | Yes |
software.version_released |
A new version of the software is out | No |
software.closed |
WordPress.org closed the software, or the package was deprecated or abandoned | No |
software.reopened |
Closed software is available again | No |
package.malicious |
A version of an npm package you watch contains malware | Yes |
project.vulnerable |
A new lockfile of a project adds versions with known vulnerabilities | Yes |
project.resolved |
A new lockfile of a project has no known vulnerabilities left | Yes |
vulnerability.exploited |
CISA lists the vulnerability's CVE as actively exploited (KEV) | Yes |
vulnerability.exploit_published |
A public exploit or proof of concept is referenced for its CVE | Yes |
vulnerability.cve_assigned |
An advisory without a CVE gets its CVE number | No |
cve.matched |
A new CVE meets one of your CVE rules | Per rule |
vulnerability.patched and patch.released differ on purpose. The first means a source says there is a fix. The second only arrives when that version is downloadable from WordPress.org or the package registry, so you can update right away. For premium software, which has no public downloads, it follows the first.
Ladon only sends patch.released when the fix came out after Ladon knew about the vulnerability. If the fix was already out when the vulnerability was published, vulnerability.created says so.
vulnerability.exploited is the strongest reason to patch now: attackers use it. Ladon sends it once per vulnerability and software, when the CVE first appears on CISA's Known Exploited Vulnerabilities list. vulnerability.exploit_published arrives when a reference to a public exploit is added, often the moment an attack becomes easy. vulnerability.cve_assigned helps with advisories Ladon read before GitHub reviewed them: you get the advisory early and the CVE number later, for tickets and reports.
The envelope
Every webhook has the same outer shape:
| Field | Type | Meaning |
|---|---|---|
id |
string | Unique id of the event, starts with evt_ |
type |
string | One of the types above |
api_version |
string | Payload version of this channel, currently 2026-11-01 |
created_at |
string | When the event happened, ISO 8601 in UTC |
team |
object | id and name of the team |
data |
object | The content, see below |
links |
object | dashboard: the alerts page of the project |
Example
{
"id": "evt_01JB8Z5X2C7Q4R9T6Y3W1M0N8P",
"type": "vulnerability.created",
"api_version": "2026-11-01",
"created_at": "2026-11-03T09:14:22Z",
"team": { "id": "acme", "name": "Acme" },
"data": {
"vulnerability": {
"id": "3f1c7a52-6a1b-4f2e-9d7c-0b8e4a2c9d11",
"title": "Example Forms <= 2.3.1 - Authenticated (Subscriber+) Stored Cross-Site Scripting",
"cve": "CVE-2026-12345",
"cvss": {
"score": 6.4,
"rating": "Medium",
"vector": "CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:C/C:L/I:L/A:N",
"version": "3.1"
},
"cwe": {
"id": 79,
"name": "Improper Neutralization of Input During Web Page Generation ('Cross-site Scripting')"
},
"informational": false,
"published_at": "2026-11-03T08:00:00Z",
"updated_at": "2026-11-03T08:00:00Z",
"references": ["https://example.com/advisories/example-forms-xss"],
"source": {
"url": "https://source.example/vulnerabilities/3f1c7a52-6a1b-4f2e-9d7c-0b8e4a2c9d11",
"copyrights": {
"example": {
"notice": "Copyright 2026 Example Inc.",
"license": "Example Inc. grants you a license to ..."
}
}
}
},
"software": {
"type": "plugin",
"ecosystem": "wordpress",
"slug": "example-forms",
"name": "Example Forms"
},
"affected_versions": [
{
"label": "* - 2.3.1",
"from": "*",
"from_inclusive": true,
"to": "2.3.1",
"to_inclusive": true
}
],
"patched": true,
"patched_versions": ["2.3.2"],
"remediation": "Update to version 2.3.2, or a newer patched version",
"severity": "medium",
"match": {
"watch_id": "wat_01JB0C3E5G7J9L2N4Q6S8U0W1Y",
"version_constraint": "<2.3.2",
"sites": []
}
},
"links": { "dashboard": "https://ladon.hackindex.io/teams/acme/alerts" }
}
The values are made up. software.type is plugin, theme or core for WordPress, npm, composer, pypi, gem, cargo, golang or maven for packages and github for a repository, the names of the package URL standard. software.ecosystem is wordpress, npm, packagist, pypi, rubygems, crates.io, go, maven or github. For packages the vulnerability id is a GitHub advisory id such as ghsa-jf85-cpcp-j695. from and to use * for "no limit". severity is critical, high, medium, low or null when there is no score. match tells which of your watches caught the event. When a project caught it, match.projects lists each project with its id, name and the installed packages, each with version, direct, dev and path.
Differences per type
| Type | What is different in data |
|---|---|
vulnerability.updated |
changes lists the fields that changed, flags has severity_changed, cve_assigned and affected_versions_changed, and previous holds the old values |
vulnerability.deleted |
Only vulnerability.id, vulnerability.title, vulnerability.source, software and reason: "withdrawn" |
vulnerability.patched |
Like created, with patched: true and the new patched_versions |
patch.released |
Like patched, plus release with version, released_at, download_url (empty for premium software, the registry page for packages) and on_wordpress_org |
software.version_released |
software and release with version, released_at and download_url |
software.closed |
software and closure with date, reason (for example security-issue) and permanent |
software.reopened |
Only software |
package.malicious |
malicious with id (an OSV id starting with MAL-) and url, software, affected_versions and severity: "critical" |
project.vulnerable |
project with id, name, kind and package_count, count, and up to 50 findings as in the project API |
project.resolved |
project, count: 0 and empty findings |
vulnerability.exploited |
Like created, plus exploitation with cve, kev.added_at, epss, epss_percentile and url, the CVE page in Ladon |
vulnerability.exploit_published |
Like created, plus exploitation with cve, the exploit references, epss, epss_percentile and url |
vulnerability.cve_assigned |
Like created, with the new number in vulnerability.cve. When only the number is new, this replaces vulnerability.updated |
CVE rules
cve.matched comes from a CVE rule and goes to the channels of that rule, whatever event types the channel has. Its data has no software or match, but:
cve:id,title,description,state,published_at,updated_at,assigner,severity(ornullwithout a score),cvsswithscore,version,vectorandsource(cnaorcisa-adp),cwe_ids,vendorsandproductsin lowercase,kevwithadded_atornull,epsswithscoreandpercentile(0 to 1) ornull, up to 25referenceswithurlandtags,urlto the record on cve.org, andsourcewithname,urlandnotices.rule:idandnameof the rule.reasons: the conditions that were true, in the language of the channel, such asseverity is critical.
links.dashboard points to the page of the rule, links.cve to the page of the CVE in Ladon. Every matched CVE is its own cve.matched message, also when one update matches many CVEs at once.
Two more types only exist as webhooks: ping when you send a test, with data.message, and endpoint.verify when Ladon checks your endpoint, with data.challenge. See Webhooks.
Summaries and bundles
A channel that sends a summary gets one message of type digest. A channel that bundles alerts, or goes over its limit per hour, gets one message of type batch. Both have the same shape: data.period has from and to, data.count the number of events, and data.events the events themselves, each with id, type, created_at and data. Long summaries are split over several messages of up to 100 events, numbered in data.part. The id of the message starts with dig_ or bat_.
Critical alerts that skip the wait arrive as normal events, not in the summary.
Source and licenses
vulnerability.source is always there. It holds url, a link to the record at the source, and copyrights, with the copyright notice and license of each party. The license of the data asks that the link, the notice and the license travel with every copy. Keep them when you publish an alert further, for example in a ticket or a report for a client. All licenses are on the licenses page.
Versioning
Each channel is pinned to an api_version. New fields can be added at any time, so ignore fields you do not know. Changes that could break an integration only come with a new api_version, announced in the changelog.