Configuring webhooks for your organization

Webhooks notify external services when a SonarQube Cloud project analysis is complete.

This page explains how to manage webhooks for your SonarQube Cloud organization. For more information about the feature, see Webhooks. You must be an organization admin to be able to manage webhooks for your organization.

• You can configure up to 10 webhooks for your organization.

• Organization-level webhooks are not replaced by project-level webhooks. All webhooks at both levels will be executed.

Creating a webhook

This paragraph explains how to create webhooks in the UI for your organization. You can also use the Web API.

1. Retrieve your organization. For more information, see Retrieving your organizations.

2. Go to Administration > Webhooks.

3. Select Create. The Create Webhook dialog is displayed.

4. Enter the webhook name.

5. Enter the URL to which the webhook is to be delivered.

6. Enter a secret if you want to protect the webhook with HMAC. See Securing webhooks below.

7. Test your webhook. To do so, you can use various webhook testing/debugging tools.

Updating or deleting a webhook

1. Retrieve your organization. For more information, see Retrieving your organizations.

2. Go to Administration > Webhooks.

3. In the three-dot menu at the far right of the webhook row, select the corresponding command.

Monitoring the webhook delivery

You can monitor the delivery of your webhooks configured for your organization in the SonarQube UI. You can also use the Web API to retrieve the webhook deliveries.

Each webhook’s delivery status is indicated. A delivery is marked as failed if the URL doesn’t respond within 10 seconds. Response records are purged after 30 days.

SonarQube Cloud doesn’t retry to deliver failed webhook deliveries. You may use the Web API to implement an automatic redelivering mechanism.

If you downgraded your organization to the Free plan, existing webhooks are still visible on the UI but won’t be invoked by SonarQube Cloud. If you upgrade your organization, you regain access to them.

To monitor your organization's webhooks:

1. Retrieve your organization. For more information, see Retrieving your organizations.

2. Go to Administration > Webhooks. The page shows the result and timestamp of each webhook’s most recent delivery.

3. To view the payload of the last delivery, select the link in the Last delivery column of the webhook row.

4. To view the results and payloads of earlier deliveries, select the three-dot menu at the far right of the webhook row.

Securing webhooks

After you’ve configured your server to receive payloads, you want to be sure that the payloads you receive are initiated by SonarQube Cloud and not by attackers. You can do this by validating a hash signature that ensures that requests originate from SonarQube Cloud.

A basic authentication mechanism is supported by providing user/password in the URL of the Webhook such as https://myLogin:myPassword@my_server/foo.

1

Set your secret

1. Retrieve your organization. For more information, see Retrieving your organizations.

2. Go to Administration > Webhooks.

3. You can either select Create to create a new webhook or click an existing webhook’s settings drop-down and select Update.

4. Enter a random string in the Secret text box. This is used as the key to generate the HMAC hex digest value in the X-Sonar-Webhook-HMAC-SHA256 header.

5. Select Update.

2

Validate the received payload

After setting your secret, it’s used by SonarQube Cloud to create a hash signature with each payload that’s passed using the X-Sonar-Webhook-HMAC-SHA256 HTTP header. The header value needs to match the signature you are expecting to receive. SonarQube Cloud uses a HMAC lower-case SHA256 digest to compute the signature of the request body. Below is some sample Java code for your server. In this example, we are using the lib from apache commons-codec HmacUtils class.

private static boolean isValidSignature(YourHttpRequest request) {
  String receivedSignature = request.getHeader("X-Sonar-Webhook-HMAC-SHA256");
  // See Apache commons-codec
  String expectedSignature = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, "your_secret").hmacHex(request.getBody())
  return Objects.equals(expectedSignature, receivedSignature);
}

If the signatures don’t match, then the payload should be ignored.

Related pages

• Webhooks (solution overview)

• Configuring webhooks for your project