# Webhook Payload

A Firewall quarantine webhook payload is the JSON body sent via HTTP POST to your configured URL when a component is quarantined by firewall due to a policy violation. The payload includes repository, component, policy, and request context. A complete structure of the payload is given below:

```
{
  "timestamp": "2026-02-23T10:56:00.000Z",
  "initiator": "admin",
  "nodeId": "node-abc123",
  "event": "FIREWALL_QUARANTINE_DOWNLOAD_BLOCKED",
  "repository": "maven-central",
  "repository_format": "maven2",
  "component_identifier": {
    "format": "maven2",
    "coordinates": {
      "groupId": "org.apache.logging.log4j",
      "artifactId": "log4j-core",
      "version": "2.14.1"
    },
    "purl": "pkg:maven/org/apache/logging/log4j/log4j-core@2.14.1"
  },
  "asset_path": "/org/apache/logging/log4j/log4j-core/2.14.1/log4j-core-2.14.1.jar",
  "asset_checksums": {
    "sha1": "fca480c9018010760e5e2e1eaed9c2b0546e7138",
    "sha256": "e16500ad571de1612e4ff8555c179b41596d6322e915b5a221e134d0571d4bf0",
    "md5": "4f100dfb02f121b34a9c472d829e9a7a"
  },
  "quarantine_status": "QUARANTINE",
  "quarantine_reasons": [
    {
      "policy_name": "Security-Critical",
      "threat_level": 10,
      "violations": [
        {
          "constraint_name": "Security Vulnerability Severity >= 9",
          "reasons": [
            "CVE-2021-44228 (CVSS Score: 10.0)",
            "CVE-2021-45046 (CVSS Score: 9.0)"
          ]
        }
      ]
    },
    {
      "policy_name": "License-Copyleft",
      "threat_level": 7,
      "violations": [
        {
          "constraint_name": "GPL License",
          "reasons": [
            "Component has GPL license"
          ]
        }
      ]
    }
  ],
  "firewall_report_url": "http://localhost:8072/ui/links/firewall/repositories/quarantinedComponent/abc123",
  "quarantine_timestamp": "2026-02-23T10:56:00.000Z",
  "action": "BLOCKED",
  "http_method": "GET",
  "http_status": 403,
  "username": "admin",
  "realm": "NexusAuthenticatingRealm",
  "user_ip_address": "192.168.1.100",
  "user_agent": "Maven/3.8.1"
}
```

## Field Descriptions

Top Level Fields

| Field                    | Description                                       |
|--------------------------|---------------------------------------------------|
| `timestamp`              | Time when the webhook was generated               |
| `initiator`              | Username of the user who triggered the download   |
| `nodeId`                 | Nexus cluster node ID that generated the event    |
| `event`                  | Always "FIREWALL_QUARANTINE_DOWNLOAD_BLOCKED"   |
| `repository`             | Repository name where download was attempted      |
| `repository_format`      | Format Name - maven2, npm, docker, pypi, nuget, etc. |
| `component_identifier`    | Optional; Parsed component coordinates (see below) |
| `asset_path`            | Full path to the asset within the repository      |
| `asset_checksums`       | Map of checksum algorithms to values              |
| `quarantine_status`     | BLOCKED or QUARANTINED                           |
| `quarantine_reasons`    | List of policy violations (see below)            |
| `firewall_report_url`   | Optional; Direct link to IQ Server report        |
| `quarantine_timestamp`   | Time when component was quarantined               |
| `action`                | BLOCKED or QUARANTINED                           |
| `http_method`           | HTTP method of the download request (usually "GET") |
| `http_status`           | HTTP status code returned (`403` for blocked)     |
| `username`              | Username from authentication                       |
| `realm`                 | Authentication realm                              |
| `user_ip_address`       | Optional; Client IP address                       |
| `user_agent`            | Optional; Client User-Agent header                |

### Component Identifier Object

| Field        | Description                                    |
|--------------|-------------------------------------------------|
| `format`    | Repository format                               |
| `coordinates` | Format specific coordinates                    |
| `purl`      | Package URL (PURL) - universal component identifier |

### Quarantine Reasons Array

| Field          | Description                                      |
|----------------|--------------------------------------------------|
| `policy_name`  | Name of the violated IQ Server policy             |
| `threat_level` | IQ threat level (0-10; higher = more severe)     |
| `violations`   | List of constraint violations within this policy  |

Every violation object contains the following fields:

| Field              | Description                                          |
|--------------------|------------------------------------------------------|
| `constraint_name`  | Name of the constraint that was violated              |
| `reasons`         | Specific reasons (CVE IDs with scores, license names, etc.) |

When `quarantine_reasons` contains only the following codeblock, it indicates a repeat access attempt to an already quarantined component (no new policy evaluation).

```
{"policy_name": "Subsequent access to previously quarantined component",
"threat_level": 0,
"violations": [ ]
}
```

## Example: Log4Shell Vulnerability Payload (First-Time Quarantine)

The following is an example payload for first time quarantine of log4Shell vulnerability.

```
{
  "event": "FIREWALL_QUARANTINE_DOWNLOAD_BLOCKED",
  "repository": "maven-central",
  "repository_format": "maven2",
  "component_identifier": {
    "format": "maven2",
    "coordinates": {
      "groupId": "org.apache.logging.log4j",
      "artifactId": "log4j-core",
      "version": "2.14.1"
    },
    "purl": "pkg:maven/org/apache/logging/log4j/log4j-core@2.14.1"
  },
  "quarantine_status": "QUARANTINED",
  "quarantine_reasons": [
    {
      "policy_name": "Security-Critical",
      "threat_level": 10,
      "violations": [
        {
          "constraint_name": "Security Vulnerability Severity >= 9",
          "reasons": [
            "CVE-2021-44228 (CVSS Score: 10.0)",
            "CVE-2021-45046 (CVSS Score: 9.0)",
            "CVE-2021-45105 (CVSS Score: 7.5)"
          ]
        }
      ]
    }
  ],
  "action": "QUARANTINED",
  "http_status": 403,
  "username": "developer",
  "user_agent": "Apache-Maven/3.8.1"
}
```

The `"action": "QUARANTINED"` indicates that it is the first time a component was evaluated and blocked. Complete policy violation details are included.

## Example: GPL License Violation Payload

The following is an example payload for first time quarantine of GPL license violation.

```
{
  "event": "FIREWALL_QUARANTINE_DOWNLOAD_BLOCKED",
  "repository": "npm-proxy",
  "repository_format": "npm",
  "component_identifier": {
    "format": "npm",
    "coordinates": {
      "packageId": "some-gpl-package",
      "version": "1.0.0"
    },
    "purl": "pkg:npm/some-gpl-package@1.0.0"
  },
  "quarantine_status": "QUARANTINED",
  "quarantine_reasons": [
    {
      "policy_name": "License-Copyleft",
      "threat_level": 7,
      "violations": [
        {
          "constraint_name": "GPL License",
          "reasons": [
            "Component has GPL-3.0 license"
          ]
        }
      ]
    }
  ],
  "action": "QUARANTINED",
  "http_status": 403
}
```

## Example: Subsequent Access Payload

The following example illustrate the webhook payload for subsequent access to a previously quarantined component.

```
{
  "event": "FIREWALL_QUARANTINE_DOWNLOAD_BLOCKED",
  "repository": "maven-central",
  "repository_format": "maven2",
  "component_identifier": {
    "format": "maven2",
    "coordinates": {
      "groupId": "org.apache.logging.log4j",
      "artifactId": "log4j-core",
      "version": "2.14.1"
    },
    "purl": "pkg:maven/org/apache/logging/log4j/log4j-core@2.14.1"
  },
  "quarantine_status": "BLOCKED",
  "quarantine_reasons": [
    {
      "policy_name": "Subsequent access to previously quarantined component",
      "threat_level": 0,
      "violations": []
    }
  ],
  "action": "BLOCKED",
  "http_status": 403,
  "username": "developer",
  "user_agent": "Apache-Maven/3.8.1"
}
```

The `"action": "BLOCKED"` indicates this component was already in quarantine. No new policy evaluation was performed. The original policy violation details are not included in this webhook.