# Events en payloads

Elke melding is een event. Op deze pagina staan alle soorten events en wat erin zit. E-mail en webhooks dragen dezelfde events, webhooks als JSON.

## Soorten events

| Type                              | Wanneer                                                                               | Standaard aan |
| --------------------------------- | ------------------------------------------------------------------------------------- | ------------- |
| `vulnerability.created`           | Een nieuwe kwetsbaarheid raakt software die je volgt                                  | Ja            |
| `vulnerability.updated`           | De titel, beschrijving, ernst, CVE, CWE, getroffen versies of de oplossing veranderde | Ja            |
| `vulnerability.deleted`           | De bron heeft de kwetsbaarheid ingetrokken                                            | Ja            |
| `vulnerability.patched`           | De bron meldt dat de kwetsbaarheid is opgelost                                        | Nee           |
| `patch.released`                  | De opgeloste versie is echt te downloaden                                             | Ja            |
| `software.version_released`       | Er is een nieuwe versie van de software                                               | Nee           |
| `software.closed`                 | WordPress.org heeft de software gesloten, of het pakket is deprecated of abandoned    | Nee           |
| `software.reopened`               | Gesloten software is weer beschikbaar                                                 | Nee           |
| `package.malicious`               | Een versie van een npm-pakket dat je volgt bevat malware                              | Ja            |
| `project.vulnerable`              | Een nieuwe lockfile van een project voegt versies met bekende kwetsbaarheden toe      | Ja            |
| `project.resolved`                | Een nieuwe lockfile van een project heeft geen bekende kwetsbaarheden meer            | Ja            |
| `vulnerability.exploited`         | CISA noemt de CVE van de kwetsbaarheid actief misbruikt (KEV)                         | Ja            |
| `vulnerability.exploit_published` | Er verschijnt een publieke exploit of proof of concept voor de CVE                    | Ja            |
| `vulnerability.cve_assigned`      | Een advisory zonder CVE krijgt zijn CVE-nummer                                        | Nee           |
| `cve.matched`                     | Een nieuwe CVE voldoet aan een van je [CVE-regels](https://ladon.hackindex.io/nl/docs/cve-rules.md)                  | Per regel     |

`vulnerability.patched` en `patch.released` verschillen bewust. De eerste betekent dat een bron zegt dat er een oplossing is. De tweede komt pas als die versie te downloaden is van WordPress.org of het pakketregister, zodat je meteen kunt updaten. Voor premium software, die geen openbare downloads heeft, volgt hij op de eerste.

Ladon stuurt `patch.released` alleen als de oplossing uitkwam nadat Ladon de kwetsbaarheid al kende. Was de oplossing er al toen de kwetsbaarheid werd gepubliceerd, dan staat dat in `vulnerability.created`.

`vulnerability.exploited` is de sterkste reden om nu te patchen: aanvallers gebruiken het lek. Ladon stuurt het één keer per kwetsbaarheid en software, zodra de CVE voor het eerst op CISA's lijst van actief misbruikte kwetsbaarheden staat. `vulnerability.exploit_published` komt als er een referentie naar een publieke exploit bij komt, vaak het moment dat een aanval makkelijk wordt. `vulnerability.cve_assigned` helpt bij advisories die Ladon al las voordat GitHub ze reviewde: je krijgt de advisory vroeg en het CVE-nummer later, voor tickets en rapportages.

## De envelope

Elke webhook heeft dezelfde buitenkant:

| Veld          | Type   | Betekenis                                        |
| ------------- | ------ | ------------------------------------------------ |
| `id`          | string | Unieke id van het event, begint met `evt_`       |
| `type`        | string | Een van de types hierboven                       |
| `api_version` | string | Payloadversie van dit kanaal, nu `2026-11-01` |
| `created_at`  | string | Wanneer het event gebeurde, ISO 8601 in UTC      |
| `team`        | object | `id` en `name` van het team                      |
| `data`        | object | De inhoud, zie hieronder                         |
| `links`       | object | `dashboard`: de meldingenpagina van het project  |

## Voorbeeld

```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" }
}
```

De waarden zijn verzonnen. `software.type` is `plugin`, `theme` of `core` voor WordPress, `npm`, `composer`, `pypi`, `gem`, `cargo`, `golang` of `maven` voor pakketten en `github` voor een repository, de namen uit de package-URL-standaard. `software.ecosystem` is `wordpress`, `npm`, `packagist`, `pypi`, `rubygems`, `crates.io`, `go`, `maven` of `github`. Bij pakketten is het `id` van de kwetsbaarheid een GitHub-advisory-id zoals `ghsa-jf85-cpcp-j695`. `from` en `to` gebruiken `*` voor "geen grens". `severity` is `critical`, `high`, `medium`, `low` of `null` als er geen score is. `match` laat zien welke van je watches het event oppikte. Pikte een [project](https://ladon.hackindex.io/nl/docs/projects.md) het op, dan staat in `match.projects` elk project met `id`, `name` en de geïnstalleerde `packages`, elk met `version`, `direct`, `dev` en `path`. Teksten uit de bron, zoals de titel en de oplossing, zijn Engels.

## Verschillen per type

| Type                              | Wat er anders is in `data`                                                                                                                                    |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vulnerability.updated`           | `changes` noemt de gewijzigde velden, `flags` bevat `severity_changed`, `cve_assigned` en `affected_versions_changed`, en `previous` de oude waarden          |
| `vulnerability.deleted`           | Alleen `vulnerability.id`, `vulnerability.title`, `vulnerability.source`, `software` en `reason: "withdrawn"`                                                 |
| `vulnerability.patched`           | Zoals created, met `patched: true` en de nieuwe `patched_versions`                                                                                            |
| `patch.released`                  | Zoals patched, plus `release` met `version`, `released_at`, `download_url` (leeg bij premium software, de registrypagina bij pakketten) en `on_wordpress_org` |
| `software.version_released`       | `software` en `release` met `version`, `released_at` en `download_url`                                                                                        |
| `software.closed`                 | `software` en `closure` met `date`, `reason` (bijvoorbeeld `security-issue`) en `permanent`                                                                   |
| `software.reopened`               | Alleen `software`                                                                                                                                             |
| `package.malicious`               | `malicious` met `id` (een OSV-id dat begint met `MAL-`) en `url`, `software`, `affected_versions` en `severity: "critical"`                                   |
| `project.vulnerable`              | `project` met `id`, `name`, `kind` en `package_count`, `count`, en maximaal 50 `findings` zoals in de [project-API](https://ladon.hackindex.io/nl/docs/projects.md#ci)                       |
| `project.resolved`                | `project`, `count: 0` en lege `findings`                                                                                                                      |
| `vulnerability.exploited`         | Zoals created, plus `exploitation` met `cve`, `kev.added_at`, `epss`, `epss_percentile` en `url`, de CVE-pagina in Ladon                                      |
| `vulnerability.exploit_published` | Zoals created, plus `exploitation` met `cve`, de exploit-`references`, `epss`, `epss_percentile` en `url`                                                     |
| `vulnerability.cve_assigned`      | Zoals created, met het nieuwe nummer in `vulnerability.cve`. Is alleen het nummer nieuw, dan komt dit in plaats van `vulnerability.updated`                   |

## CVE-regels {#cve-matched}

`cve.matched` komt van een [CVE-regel](https://ladon.hackindex.io/nl/docs/cve-rules.md) en gaat naar de kanalen van die regel, welke eventtypes het kanaal ook heeft. De `data` heeft geen `software` of `match`, maar:

- `cve`: `id`, `title`, `description`, `state`, `published_at`, `updated_at`, `assigner`, `severity` (of `null` zonder score), `cvss` met `score`, `version`, `vector` en `source` (`cna` of `cisa-adp`), `cwe_ids`, `vendors` en `products` in kleine letters, `kev` met `added_at` of `null`, `epss` met `score` en `percentile` (0 tot 1) of `null`, maximaal 25 `references` met `url` en `tags`, `url` naar het record op cve.org, en `source` met `name`, `url` en `notices`.
- `rule`: `id` en `name` van de regel.
- `reasons`: de voorwaarden die waar waren, in de taal van het kanaal, zoals `ernst is kritiek`.

`links.dashboard` wijst naar de pagina van de regel, `links.cve` naar de pagina van de CVE in Ladon. Elke CVE die past, is een eigen `cve.matched`-bericht, ook als één update op veel CVE's tegelijk past.

Twee types bestaan alleen als webhook: `ping` als je een test stuurt, met `data.message`, en `endpoint.verify` als Ladon je endpoint controleert, met `data.challenge`. Zie [Webhooks](https://ladon.hackindex.io/nl/docs/webhooks.md).

## Samenvattingen en bundels

Een kanaal dat een samenvatting stuurt, krijgt één bericht van type `digest`. Een kanaal dat meldingen bundelt, of boven zijn limiet per uur komt, krijgt één bericht van type `batch`. Beide hebben dezelfde vorm: `data.period` heeft `from` en `to`, `data.count` het aantal events en `data.events` de events zelf, elk met `id`, `type`, `created_at` en `data`. Lange samenvattingen worden verdeeld over meerdere berichten van maximaal 100 events, genummerd in `data.part`. Het `id` van het bericht begint met `dig_` of `bat_`.

Kritieke meldingen die niet wachten, komen binnen als gewone events, niet in de samenvatting.

## Bron en licenties

`vulnerability.source` is er altijd. Het bevat `url`, een link naar het record bij de bron, en `copyrights`, met per partij de copyrightvermelding en licentie. De licentie van de gegevens vraagt dat de link, de vermelding en de licentie bij elke kopie blijven. Laat ze staan als je een melding verder publiceert, bijvoorbeeld in een ticket of een rapport voor een klant. Alle licenties staan op de [licentiepagina](https://ladon.hackindex.io/licenties).

## Versies van de payload

Elk kanaal staat vast op een `api_version`. Nieuwe velden kunnen altijd bijkomen, dus negeer velden die je niet kent. Wijzigingen die een koppeling kunnen breken, komen alleen met een nieuwe `api_version` en worden aangekondigd in de changelog.
