Skip to content
HackIndex Ladon
Menu

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 (or null without a score), cvss with score, version, vector and source (cna or cisa-adp), cwe_ids, vendors and products in lowercase, kev with added_at or null, epss with score and percentile (0 to 1) or null, up to 25 references with url and tags, url to the record on cve.org, and source with name, url and notices.
  • rule: id and name of the rule.
  • reasons: the conditions that were true, in the language of the channel, such as severity 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.