# Notification Webhooks (Open Source)

**This is an experimental Open Source feature — behavior may change in future releases.**

Webhooks are outbound HTTP requests sent from your DefectDojo instance to a user-defined server whenever specific events occur.

## Setup

Webhook endpoints are configured by admins. When a webhook is created, DefectDojo sends a [`ping`](https://docs.defectdojo.com/automation/api/notification_webhooks/#ping) event to verify the endpoint is reachable and returning the expected status code.

## Endpoint State Transitions

DefectDojo monitors delivery success and will temporarily or permanently disable an endpoint based on HTTP responses or network failures. Manual re-activation by an admin is also possible.

- **Stadium-shaped states**: Active — webhooks can be sent
- **Rectangle states**: Inactive — webhook delivery will fail and is not retried
- **Transitions driven by**: HTTP responses from the target server, celery automation, or manual admin action

## Request Headers

Every webhook request includes the following headers:

```yaml
User-Agent: DefectDojo-<version>
X-DefectDojo-Event: <event_name>
X-DefectDojo-Instance: <base_url_of_dd_instance>
```

## Events

### product_type_added

Fired when a new Product Type is created.

**Header:**

```yaml
X-DefectDojo-Event: product_type_added
```

**Body:**

```json
{
    "description": "",
    "title": "",
    "product_type": {
        "id": 4,
        "name": "notif prod type",
        "url_api": "http://localhost:8080/api/v2/product_types/4/",
        "url_ui": "http://localhost:8080/product/type/4"
    },
    "url_api": "http://localhost:8080/api/v2/product_types/4/",
    "url_ui": "http://localhost:8080/product/type/4",
    "user": {
        "id": 1,
        "email": "admin@defectdojo.local",
        "first_name": "Admin",
        "last_name": "User",
        "username": "admin",
        "url_api": "http://localhost:8080/api/v2/users/1/",
        "url_ui": "http://localhost:8080/user/1"
    }
}
```

---

### product_added

Fired when a new Product is created.

**Header:**

```yaml
X-DefectDojo-Event: product_added
```

**Body:**

```json
{
    "description": "",
    "title": "",
    "product": {
        "id": 4,
        "name": "notif prod",
        "url_api": "http://localhost:8080/api/v2/products/4/",
        "url_ui": "http://localhost:8080/product/4"
    },
    "product_type": {
        "id": 4,
        "name": "notif prod type",
        "url_api": "http://localhost:8080/api/v2/product_types/4/",
        "url_ui": "http://localhost:8080/product/type/4"
    },
    "url_api": "http://localhost:8080/api/v2/products/4/",
    "url_ui": "http://localhost:8080/product/4",
    "user": {
        "id": 1,
        "email": "admin@defectdojo.local",
        "first_name": "Admin",
        "last_name": "User",
        "username": "admin",
        "url_api": "http://localhost:8080/api/v2/users/1/",
        "url_ui": "http://localhost:8080/user/1"
    }
}
```

---

### engagement_added

Fired when a new Engagement is created.

**Header:**

```yaml
X-DefectDojo-Event: engagement_added
```

**Body:**

```json
{
    "description": "",
    "title": "",
    "engagement": {
        "id": 7,
        "name": "notif eng",
        "url_api": "http://localhost:8080/api/v2/engagements/7/",
        "url_ui": "http://localhost:8080/engagement/7"
    },
    "product": {
        "id": 4,
        "name": "notif prod",
        "url_api": "http://localhost:8080/api/v2/products/4/",
        "url_ui": "http://localhost:8080/product/4"
    },
    "product_type": {
        "id": 4,
        "name": "notif prod type",
        "url_api": "http://localhost:8080/api/v2/product_types/4/",
        "url_ui": "http://localhost:8080/product/type/4"
    },
    "url_api": "http://localhost:8080/api/v2/engagements/7/",
    "url_ui": "http://localhost:8080/engagement/7",
    "user": {
        "id": 1,
        "email": "admin@defectdojo.local",
        "first_name": "Admin",
        "last_name": "User",
        "username": "admin",
        "url_api": "http://localhost:8080/api/v2/users/1/",
        "url_ui": "http://localhost:8080/user/1"
    }
}
```

---

### test_added

Fired when a new Test is created.

**Header:**

```yaml
X-DefectDojo-Event: test_added
```

**Body:**

---

### scan_added / scan_added_empty

Fired when a scan is imported or reimported. `scan_added_empty` fires when a reimport results in no changes (no findings created or closed).

**Headers:**

```yaml
X-DefectDojo-Event: scan_added
```

```yaml
X-DefectDojo-Event: scan_added_empty
```

**Body:**

```json
{
    "description": "",
    "title": "",
    "engagement": {
        "id": 7,
        "name": "notif eng",
        "url_api": "http://localhost:8080/api/v2/engagements/7/",
        "url_ui": "http://localhost:8080/engagement/7"
    },
    "finding_count": 4,
    "findings": {
        "mitigated": [\
            {\
                "id": 233,\
                "severity": "Medium",\
                "title": "Mitigated Finding",\
                "url_api": "http://localhost:8080/api/v2/findings/233/",\
                "url_ui": "http://localhost:8080/finding/233"\
            }\
        ],\
        "new": [\
            {\
                "id": 232,\
                "severity": "Critical",\
                "title": "New Finding",\
                "url_api": "http://localhost:8080/api/v2/findings/232/",\
                "url_ui": "http://localhost:8080/finding/232"\
            }\
        ],\
        "reactivated": [\
            {\
                "id": 234,\
                "severity": "Low",\
                "title": "Reactivated Finding",\
                "url_api": "http://localhost:8080/api/v2/findings/234/",\
                "url_ui": "http://localhost:8080/finding/234"\
            }\
        ],\
        "untouched": [\
            {\
                "id": 235,\
                "severity": "Info",\
                "title": "Untouched Finding",\
                "url_api": "http://localhost:8080/api/v2/findings/235/",\
                "url_ui": "http://localhost:8080/finding/235"\
            }\
        ]\
    },
    "product": {
        "id": 4,
        "name": "notif prod",
        "url_api": "http://localhost:8080/api/v2/products/4/",
        "url_ui": "http://localhost:8080/product/4"
    },
    "product_type": {
        "id": 4,
        "name": "notif prod type",
        "url_api": "http://localhost:8080/api/v2/product_types/4/",
        "url_ui": "http://localhost:8080/product/type/4"
    },
    "test": {
        "id": 90,
        "title": "notif test",
        "url_api": "http://localhost:8080/api/v2/tests/90/",
        "url_ui": "http://localhost:8080/test/90"
    },
    "url_api": "http://localhost:8080/api/v2/tests/90/",
    "url_ui": "http://localhost:8080/test/90",
    "user": {
        "id": 1,
        "email": "admin@defectdojo.local",
        "first_name": "Admin",
        "last_name": "User",
        "username": "admin",
        "url_api": "http://localhost:8080/api/v2/users/1/",
        "url_ui": "http://localhost:8080/user/1"
    }
}
```

---

### ping

Sent during webhook setup to verify the endpoint is reachable.

**Header:**

```yaml
X-DefectDojo-Event: ping
```

**Body:**

```json
{
    "description": "Test webhook notification",
    "title": "",
    "user": {
        "id": 1,
        "email": "admin@defectdojo.local",
        "first_name": "Admin",
        "last_name": "User",
        "username": "admin",
        "url_api": "http://localhost:8080/api/v2/users/1/",
        "url_ui": "http://localhost:8080/user/1"
    }
}
```

## Roadmap

Known planned improvements:

- SLA-related events (not yet supported)
- User-defined webhooks (currently admin-only)
- Improved UI with filtering and pagination for webhook endpoints