Title here
Summary here
Notification Webhooks (experimental)
Webhooks are HTTP requests coming from the DefectDojo instance towards a user-defined webserver which expects this kind of incoming traffic.
Transition graph:
It is not unusual that in some cases a webhook can not be delivered. It is usually connected to network issues, server misconfiguration, or running upgrades on the server. DefectDojo needs to react to these outages. It might temporarily or permanently disable related endpoints. The following graph shows how it might change the status of the webhook definition based on HTTP responses (or manual user interaction).
flowchart TD
START{{Endpoint created}}
ALL{All states}
STATUS_ACTIVE([STATUS_ACTIVE])
STATUS_INACTIVE_TMP
STATUS_INACTIVE_PERMANENT
STATUS_ACTIVE_TMP([STATUS_ACTIVE_TMP])
END{{Endpoint removed}}
START ==> STATUS_ACTIVE
STATUS_ACTIVE --HTTP 200 or 201 --> STATUS_ACTIVE
STATUS_ACTIVE --HTTP 5xx
or HTTP 429
or Timeout--> STATUS_INACTIVE_TMP STATUS_ACTIVE --Any HTTP 4xx response
or any other HTTP response
or non-HTTP error--> STATUS_INACTIVE_PERMANENT STATUS_INACTIVE_TMP -.After 60s.-> STATUS_ACTIVE_TMP STATUS_ACTIVE_TMP --HTTP 5xx
or HTTP 429
or Timeout
within 24h
from the first error-->STATUS_INACTIVE_TMP STATUS_ACTIVE_TMP -.After 24h.-> STATUS_ACTIVE STATUS_ACTIVE_TMP --HTTP 200 or 201 --> STATUS_ACTIVE_TMP STATUS_ACTIVE_TMP --HTTP 5xx
or HTTP 429
or Timeout
within 24h from the first error
or any other HTTP response or error--> STATUS_INACTIVE_PERMANENT ALL ==Activation by user==> STATUS_ACTIVE ALL ==Deactivation by user==> STATUS_INACTIVE_PERMANENT ALL ==Removal of endpoint by user==> END
or HTTP 429
or Timeout--> STATUS_INACTIVE_TMP STATUS_ACTIVE --Any HTTP 4xx response
or any other HTTP response
or non-HTTP error--> STATUS_INACTIVE_PERMANENT STATUS_INACTIVE_TMP -.After 60s.-> STATUS_ACTIVE_TMP STATUS_ACTIVE_TMP --HTTP 5xx
or HTTP 429
or Timeout
within 24h
from the first error-->STATUS_INACTIVE_TMP STATUS_ACTIVE_TMP -.After 24h.-> STATUS_ACTIVE STATUS_ACTIVE_TMP --HTTP 200 or 201 --> STATUS_ACTIVE_TMP STATUS_ACTIVE_TMP --HTTP 5xx
or HTTP 429
or Timeout
within 24h from the first error
or any other HTTP response or error--> STATUS_INACTIVE_PERMANENT ALL ==Activation by user==> STATUS_ACTIVE ALL ==Deactivation by user==> STATUS_INACTIVE_PERMANENT ALL ==Removal of endpoint by user==> END
Notes:
- Transitions:
- bold: manual changes by user
- dotted: automated by celery
- others: based on responses on webhooks
- Nodes:
- Stadium-shaped: Active - following webhook can be sent
- Rectangles: Inactive - performing of webhook will fail (and not retried)
- Hexagonal: Initial and final states
- Rhombus: All states (meta node to make the graph more readable)
Body and Headers
The body of each request is JSON which contains data about related events like names and IDs of affected elements. Examples of bodies are on pages related to each event (see below).
Each request contains the following headers. They might be useful for better handling of events by the server receiving them.
User-Agent: DefectDojo-<version of DD>
X-DefectDojo-Event: <name of the event>
X-DefectDojo-Instance: <Base URL for DD instance>Disclaimer
This functionality is new and in experimental mode. This means functionality might generate breaking changes in following DefectDojo releases and might not be considered final.
However, the community is open to feedback to make this functionality better and get it stable as soon as possible.
Roadmap
There are a couple of known issues that are expected to be resolved as soon as core functionality is considered ready.
- Support events - Not only adding products, product types, engagements, tests, or upload of new scans but also events around SLA
- User webhook - right now only admins can define webhooks; in the future, users will also be able to define their own
- Improvement in UI - add filtering and pagination of webhook endpoints