Using VDR WebHooks for Reporting

This article summarizes the webhooks that exists for certain Secureworks® Taegis™ VDR API calls for Reporting. Webhooks allow API integrators to be notified of certain events in the system. They are simple, publicly accessible, callback URLs triggered when certain conditions are met.

Sample request performed by VDR:

POST /scan-success-example
Content-Type: application/json

{"assetId": "1", "assetType": "site", "attemptNumber": 1, "id": "39836", "isAdHoc": true, "kind": "scan", "status": "done"}

POST /scan-failure-example
Content-Type: application/json

{"assetId": "1", "assetType": "site", "attemptNumber": 2, "id": "39836", "isAdHoc": true, "kind": "scan", "status": "failed"}


POST /export-complete-example
Content-Type: application/json

{"id": "212", "kind": "export", "status": "done"}

The data posted to the endpoint matches a stripped-down version of the Public API data type. The implementors are given just enough information to poll-back the Public API to obtain the details.

Global Registry ⫘

Webhooks are registered per organization using connectors. All connectors can register callbacks and they are all optional. To do so, the connectors must expose their capabilities using the delve.json format.

Connectors can be registered via the Public API /connectors route.

{
    "scanSuccessWebhook": {
        "url": "http://example.com/success"
    },
    "scanFailureWebhook": {
        "url": "http://example.com/failure"
    },
    "exportCompleteWebhook": {
        "url": "http://example.com/export"
    }
}

Export Registry ⫘

When generating an export through the API, a webhook can be added per-request rather than globally.

curl -XPOST https://<YOUR_INSTANCE>.vdr.secureworks.com/api/v2/vulnerability-groups/export -H 'Content-Type: application/json' -d '
{
    "fileFormat": "csv",
    "kind": "export",
    "query": {"asset": {"id": 133}},
    "webhook": {
        "url": "http://example.com/exports/111-1221"
    }
}'

Request Signature ⫘

The webhooks are signed using a JWT token and passed in the Authorization header. In order to prevent unauthorized access, it is recommended to validate the signature.

The signature payload is the body payload with the added iat attribute. We do not force an expiry. However, we recommend validating that the signature was generated within a reasonable time span. When using the signed version, the request body can be entirely discarded as it brings no additional value.

The X-Signature header is also provided to confirm the algorithm and location of the key to be used to validate the signature. These values can be used as additional validation.

Authorization: Signed eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzUxMiJ9.eyJpZCI6IjIxNCIsImtpbmQiOiJleHBvcnQiLCJzdGF0dXMiOiJkb25lIiwiaWF0IjoxNTk4NTM5MzkyfQ.APRD1miLkn_S9eZubK6c4Uz
hCrq8Nz35ni6AUNjs62msOyfHLqDflSvVeKMUtCTpZeSvDYqVpcb4Nszaku3JWm8RAQamueuvX4eVsy3yS5r8U_l3JAwUxLLxB3XPmxGqFd6KkPnFyXVUzMJYof2V-RexuL8pYxGZlarxDon1rRJTR6Dx
X-Signature: 'ES512 /api/webhook.key