Understanding the Webhook Payload

Coverity on Polaris
Version
latest
A webhook returns one of two payload types when it is triggered.

The payload returned by a webhook depends on the event that triggered it and on the way the project was set up. Two main types are possible:

  • Job failed
  • Scan completed

A run id is assigned only when a scan completes successfully, and when that happens the response type is "scan completed." If the scan does not complete, the job fails. Then there is no run id and a JobFailed response is sent, containing a job id instead.

Payload Properties

All the properties and attributes that a payload might contain are in the following two tables.

Properties

Name Always returned? Type Description
data.branch No obj Identifies the source-control branch associated with the job. If none as been assigned, the value will be null.
data.job Yes (if job failed) obj Job information is only available for failed jobs. Contains information about the job that triggered the webhook, and why a job failed.
data.project Yes obj The name of the project associated with this job.
data.revision No obj Identifies the revision of a completed scan. If none was assigned, the value returned is null.
data.run Yes (if scan completed) obj Run information is only included in successful scans. When a scan completes, and results are returned from the underlying tool, the results are associated with a run id.
status Yes string Values include: SUCCESS, FAILED.
type Yes string The type of webhook. Possible values include: JobFailed, ScanCompleted.
version Yes int Refers to the version of the response schema.

The information you most likely need is contained in the job or run property. The contents of job will tell you why a job failed. The run-id can be used to query for the results of the scan.

Attributes for data.project/branch/job/run

Name Always returned? Type Description
id Yes string The unique id associated with the project, branch, or revision.
link Yes string A URL that leads to more detailed information. In the case of data.job.link, it contains information about why the job failed. For details about the results of a scan, see data.run.link.
name No string The name of the project, branch, or revision.
runType Yes string Possible values: codeAnalysisRun

The attributes in this table are used in the same way for data.project, data.branch, data.job and data.run; however, a response never includes all of those properties and some of them might have a value of null, rather than contain any attributes.

Scan Completed


{
    "type": "ScanCompleted",
    "status": "SUCCESS",
    "version": 0,
    "webLink": "https://subdomain.cop.blackduck.com/projects/97458c76-56a2-4041-8ead-5652f6a37c6d/branches/e369476e-f803-4d34-a614-275f76e076cf",
    "data": {
        "project": {
            "id": "97458c76-56a2-4041-8ead-5652f6a37c6d",
            "name": "backend",
            "link": "https://subdomain.cop.blackduck.com/api/common/v0/projects/97458c76-56a2-4041-8ead-5652f6a37c6d"
            },
        "branch": {
            "id": "e369476e-f803-4d34-a614-275f76e076cf",
            "name": "main",
            "link": "https://subdomain.cop.blackduck.com/api/common/v0/branches/e369476e-f803-4d34-a614-275f76e076cf"
            },
        "revision": {
           "id": "9e31bb69-4c40-483c-8f86-e88740d52b30",
           "name": "revision1",
           "link": "https://subdomain.cop.blackduck.com/api/common/v0/revisions/9e31bb69-4c40-483c-8f86-e88740d52b30"
           },
        "run": {
            "id": "bc3ae4fa-f8bc-4455-9fad-cbf23cde51ae",
            "runType": "CodeAnalysisRun",
            "link": "https://subdomain.cop.blackduck.com/api/common/v0/runs/bc3ae4fa-f8bc-4455-9fad-cbf23cde51ae"
            }
    }
}

Job Failed


{
   "type": "JobFailed",
   "status": "FAILED",
   "version": 0,
   "webLink": "https://subdomain.cop.blackduck.com/projects/d24ec4e9-e6aa-4299-b64c-218f83dc9b62/branches/1e830b51-e1d4-44a5-bcf3-90a258d5d5e8",
   "data": {
        "project": {
            "id": "d24ec4e9-e6aa-4299-b64c-218f83dc9b62",
            "name": "swip-backend",
            "link": "https://subdomain.cop.blackduck.com/api/common/v0/projects/d24ec4e9-e6aa-4299-b64c-218f83dc9b62"
            },
        "branch": {
            "id": "1e830b51-e1d4-44a5-bcf3-90a258d5d5e8",
            "name": "master",
            "link": "https://subdomain.cop.blackduck.com/api/common/v0/branches/1e830b51-e1d4-44a5-bcf3-90a258d5d5e8"
            },
        "job": {
            "id": "rq228sr69t4rp5pvnv9f9kd7eg",
            "link": "https://subdomain.cop.blackduck.com/api/jobs/v0/jobs/rq228sr69t4rp5pvnv9f9kd7eg"
            }
   }
}