Create a Webhook

A webhook listens for a predetermined event and sends data to an endpoint when the event happens, triggering an action controlled by the remote endpoint. Coverity on Polaris sends such callbacks to an external system, allowing it to react to a change without the need to constantly poll for the change.

Note: The creation, updating, and deletion of webhooks and project webhooks is restricted to organization administrators only. All users can read the webhooks.

About webhooks

A Coverity on Polaris webhook is defined as a URL combined with a well-defined data payload that is sent to that URL from a service.

The following activity diagram shows when a webhook is delivered and when mutual authorization is used.

About Mutual Authentication

Mutual authentication happens when two parties verify their identities for one another, usually simultaneously. It prevents sensitive data from being sent to an incorrect endpoint, because it verifies both the sender and recipient of the data.

For Coverity on Polaris, mutual authentication is optional and can be enabled or disabled by the organization administrator. If the mutual verification fails at any step, the payload is not sent.

The following diagram shows the mutual authentication process using TLS certificates.

A diagram of the steps for mutual authentication. 1. Client requests a resource. 2. Server presents a certificate. 3. Client verifies certificate. 4. Client presents certificate. 5. Server verifies certificate. 6. Access to resources granted.

These are the requirements for configuring mutual authentication for a webhook target server:

The target server must be configured to serve requests with HTTPS (TLS 1.2).
The target must use a valid certificate from a certification authority trusted by Coverity on Polaris.
The target server must import the Coverity on Polaris CA certificate into its runtime trust store so that incoming requests from Coverity on Polaris can be verified against the Coverity on Polaris CA.

The Coverity on Polaris CA Certificate

The server that is the webhook target needs to import the Coverity on Polaris CA certificate into its trust store. The certificate can be downloaded from the following URL.

GET/api/notifications/certs/polaris-ca.crt

Create the webhook

Request:


// POST https://subdomain.cop.blackduck.com/api/notifications/v0
/webhooks 

{
"data": {
       "type": "webhook",
       "attributes": {
         "url": "https://webhook.site/529870de-bc00-4463-8000-
         70ea5ff8326d",
         "name": "My Webhook",
         "enabled": "true"
       }
    }
}

Always use POST to create a project-webhook association.

Make sure your payload contains both the url and the name values for the webhook – these are required. This example creates a webhook known as My Webhook, which reports to the URL stored under data.url.This webhook is enabled, because data.enabled is set to true.