# Payload

Every delivery body is one [OSV 1.9.2](https://ossf.github.io/osv-schema/) record. Facts OSV has no field for are under `database_specific`. The body's JSON Schema is at [/schemas/webhook-v1.json](/schemas/webhook-v1.json).

## Content modes

Each endpoint has a `content` setting. The default, `structured`, sends no text that a third party wrote. See [Security](/docs/security/) for why.

| | `structured` (default) | `full` |
| --- | --- | --- |
| `summary`, `details`, `credits` | Omitted | Sent |
| `references` | Only URLs the service builds from validated IDs | As the sources gave them |
| IDs, versions, package names, CVSS vectors | Sent when they match their pattern, dropped when not | Sent |
| Vendor and product names | Cleaned, sent if within 128 characters and a fixed character set | Sent as given |
| Numbers, dates, enumerated values | Sent | Sent |
| Attribution | Source name and a link to [Attribution](/docs/attribution/) | Notices and licence text |
| Marking | `content: "structured"`, `omitted`: count of dropped values | `content: "full"`, `untrusted_fields`: JSON pointers to third-party text |

In both modes invisible characters (controls, zero-width, bidi overrides, Unicode tags, supplementary variation selectors) are removed from all text, and a body that had any removed carries `sanitized: true`.

## Record fields

| Field | Built from |
| --- | --- |
| `id` | CVE ID when one exists, else GHSA ID, else Drupal OSV ID (`DRUPAL-CONTRIB-2026-001`), else `x_WORDFENCE-<uuid>` |
| `aliases` | Every other known ID |
| `published` | Earliest publication time across sources |
| `modified` | Time of the last rebuild that changed the record materially |
| `withdrawn` | CVE state `REJECTED`, GHSA withdrawal, or a Wordfence deletion |
| `summary`, `details` | CVE title and description, else GHSA, Drupal or Wordfence text. `full` only |
| `severity` | One entry per distinct CVSS vector, typed `CVSS_V2`, `CVSS_V3` or `CVSS_V4` |
| `affected[].package` | Ecosystem and name from GHSA, Drupal, Wordfence. WordPress uses `WordPress:Plugin`, `WordPress:Theme`, `WordPress:Core` |
| `affected[].ranges`, `versions` | GHSA, the Drupal OSV files, Wordfence |
| `affected[].database_specific` | `vendor`, `product`, `cpes` and the CVE record's version entries, unconverted, for entries with no package |
| `references` | See content modes |

A record whose `affected` entries carry vendor and product but no `package` is valid OSV. CVE-record version data is passed through unconverted.

## database_specific

| Field | Meaning |
| --- | --- |
| `event` | `{ id, type, changed, created }`. `type` is `published`, `updated`, `kev_added` or `withdrawn`. `changed` names what differs for `updated`: `severity`, `affected`, `aliases`, `drupal`, `kev`, `withdrawn`, `epss`. `test: true` on a test event |
| `sources` | Sources that contributed: `cve`, `nvd`, `ghsa`, `drupal`, `drupal_osv`, `kev`, `wordfence`, `epss` |
| `cvss` | `[{ version, base_score, vector, source }]`. OSV's `severity` holds no number, so scores are here, beside the issuer: `cna`, `adp:cisa`, `nvd`, `ghsa`, `wordfence` |
| `max_base_score` | Highest base score, or `null`. Versions 3.x and 4.0 are compared as if on one scale |
| `epss` | `{ score, percentile, date }` from FIRST |
| `kev` | `{ date_added, due_date, ransomware_use }` from CISA KEV |
| `drupal` | `{ advisory_id, risk }` |
| `wordfence` | `{ id, url }` |
| `cwes` | CWE IDs |
| `cve_state`, `nvd_status` | As the sources state them |
| `previous_id` | Set when a record keyed by a GHSA, Drupal or Wordfence ID gains a CVE ID and is re-keyed |
| `attribution` | Per-source notice, see [Attribution](/docs/attribution/) |
| `content`, `omitted`, `untrusted_fields`, `sanitized` | See content modes |

## Events

| Type | Raised when |
| --- | --- |
| `published` | A record is first stored and its source published it within the last 7 days |
| `updated` | The record's material facts change: CVSS vectors and scores, affected entries, aliases, Drupal risk |
| `kev_added` | The CVE appears in CISA's KEV catalog |
| `withdrawn` | The CVE is rejected or the advisory withdrawn |

Description text, references, timestamps and NVD status are not material: changing them raises no event. An EPSS score raises `updated` with `epss` in `changed` only when it crosses a `min_epss` value some filter uses.

The service is forward-only: advisories published before it started are not backfilled.

## Example delivery (structured)

```http
POST /hole-monitor HTTP/1.1
Host: hooks.example.com
content-type: application/json
webhook-id: dlv_01jd8m3k7q4x9w2v5n6p8r0s1t
webhook-timestamp: 1763700000
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
```

```json
{
  "schema_version": "1.9.2",
  "id": "CVE-2026-12345",
  "modified": "2026-11-20T14:05:11.000Z",
  "published": "2026-11-20T13:58:02.000Z",
  "aliases": ["GHSA-abcd-efgh-jkmp"],
  "severity": [{ "type": "CVSS_V3", "score": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H" }],
  "affected": [
    {
      "package": { "ecosystem": "npm", "name": "example-lib" },
      "ranges": [{ "type": "SEMVER", "events": [{ "introduced": "0" }, { "fixed": "4.2.1" }] }]
    }
  ],
  "references": [
    { "type": "ADVISORY", "url": "https://www.cve.org/CVERecord?id=CVE-2026-12345" },
    { "type": "ADVISORY", "url": "https://nvd.nist.gov/vuln/detail/CVE-2026-12345" },
    { "type": "ADVISORY", "url": "https://github.com/advisories/GHSA-abcd-efgh-jkmp" }
  ],
  "database_specific": {
    "sources": ["cve", "ghsa"],
    "cvss": [{ "version": "3.1", "base_score": 9.8, "vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H", "source": "ghsa" }],
    "max_base_score": 9.8,
    "attribution": [
      { "source": "cve", "url": "https://holemonitor.live/docs/attribution#cve" },
      { "source": "ghsa", "url": "https://holemonitor.live/docs/attribution#ghsa" }
    ],
    "content": "structured",
    "omitted": 0,
    "event": { "id": "evt_01jd8m3k5c2b7a9z4y6x8w0v1u", "type": "published", "changed": [], "created": "2026-11-20T14:05:11.000Z" }
  }
}
```

The IDs, package and scores in this example are placeholders.

## Verification request

A new endpoint receives one signed request whose body is:

```json
{ "type": "verification", "endpoint_id": "ep_...", "code": "...", "instructions": "..." }
```

Answer with a 2xx response whose body contains the code, or submit the code with `POST /v1/endpoints/{id}/verify`. The verification body is not an OSV record; a receiver can tell it apart by its top-level `type`.
