# Events and payloads

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](https://ladon.hackindex.io/docs/cve-rules.md)                        | 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

```json
{
    "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](https://ladon.hackindex.io/docs/projects.md) 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](https://ladon.hackindex.io/docs/projects.md#ci)                          |
| `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}

`cve.matched` comes from a [CVE rule](https://ladon.hackindex.io/docs/cve-rules.md) 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](https://ladon.hackindex.io/docs/webhooks.md).

## 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](https://ladon.hackindex.io/licenties).

## 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.
