From 0ad8e318461b7d22d0cb4ab27b3a31538e57098a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A1udia?= Date: Tue, 6 Oct 2026 09:20:41 +0100 Subject: [PATCH 1/2] docs: clarify that the webhook event covers quality analysis only quality.analysis.completed reports quality analysis (including SAST and SCA). It does not report coverage, DAST or container scanning, and there is no coverage webhook yet. Adds a "What the event doesn't cover" section and says "quality analysis" in the intro and description. Co-Authored-By: Claude Sonnet 5.5 --- docs/organizations/integrations/webhooks.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/organizations/integrations/webhooks.md b/docs/organizations/integrations/webhooks.md index af06cc71eb..8f3764deb5 100644 --- a/docs/organizations/integrations/webhooks.md +++ b/docs/organizations/integrations/webhooks.md @@ -1,5 +1,5 @@ --- -description: Configure webhook endpoints to receive a real-time HTTP notification whenever Codacy finishes analyzing a branch or a pull request in your organization. +description: Configure webhook endpoints to receive a real-time HTTP notification whenever Codacy finishes the quality analysis of a branch or a pull request in your organization. --- # Webhooks @@ -10,7 +10,7 @@ description: Configure webhook endpoints to receive a real-time HTTP notificatio end="" %} -Webhooks let Codacy push a real-time HTTP notification to an endpoint you control whenever Codacy finishes analyzing a branch or a pull request, instead of you having to poll the Codacy API for updates. Once you add an endpoint, Codacy posts events from every repository of your organization to it. +Webhooks let Codacy push a real-time HTTP notification to an endpoint you control whenever Codacy finishes the quality analysis of a branch or a pull request, instead of you having to poll the Codacy API for updates. Once you add an endpoint, Codacy posts events from every repository of your organization to it. ## Adding a webhook endpoint {: id="adding-a-webhook-endpoint"} @@ -55,6 +55,15 @@ Codacy sends the event regardless of the analysis outcome, not only when it succ Codacy sends one copy of each event to every webhook endpoint of your organization, and there's no way to filter by repository or branch. +## What the event doesn't cover {: id="what-the-event-doesnt-cover"} + +`quality.analysis.completed` reports the outcome of Codacy's quality analysis, including SAST and SCA. It doesn't report the outcome of: + +- **Coverage analysis.** Codacy processes the coverage data you upload apart from the quality analysis, so the event doesn't tell you whether Codacy received or processed coverage for a commit, and `status` doesn't reflect it. Codacy doesn't send a webhook event for coverage analysis yet. +- **DAST and container scanning.** + +To check whether Codacy received the coverage data for a pull request, call [`getPullRequestCoverageReports`](https://api.codacy.com/api/api-docs#getpullrequestcoveragereports). See [identifying commits without coverage data](../../codacy-api/examples/identifying-commits-without-coverage-data.md) for an example. + ## Delivery payload {: id="delivery-payload"} Each delivery is an HTTP `POST` request with a JSON body and these headers: From 45a7f7ca36dd61b9ff3cd4c7220a05a8d4a0eab9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A1udia?= Date: Tue, 6 Oct 2026 09:26:17 +0100 Subject: [PATCH 2/2] docs: warn that SCA runs send extra webhook deliveries for the same commit For organizations with SCA, the SCA run on the head commit of the main branch sends its own quality.analysis.completed delivery. Adds a row to the delivery table and an important note under Delivery behavior, and links to it from the "What the event doesn't cover" section. Co-Authored-By: Claude Sonnet 5.5 --- docs/organizations/integrations/webhooks.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/organizations/integrations/webhooks.md b/docs/organizations/integrations/webhooks.md index 8f3764deb5..cd09ac86ce 100644 --- a/docs/organizations/integrations/webhooks.md +++ b/docs/organizations/integrations/webhooks.md @@ -57,7 +57,7 @@ Codacy sends one copy of each event to every webhook endpoint of your organizati ## What the event doesn't cover {: id="what-the-event-doesnt-cover"} -`quality.analysis.completed` reports the outcome of Codacy's quality analysis, including SAST and SCA. It doesn't report the outcome of: +`quality.analysis.completed` reports the outcome of Codacy's quality analysis, including SAST and SCA. SCA runs send their own deliveries, see [delivery behavior](#delivery-behavior). The event doesn't report the outcome of: - **Coverage analysis.** Codacy processes the coverage data you upload apart from the quality analysis, so the event doesn't tell you whether Codacy received or processed coverage for a commit, and `status` doesn't reflect it. Codacy doesn't send a webhook event for coverage analysis yet. - **DAST and container scanning.** @@ -151,9 +151,13 @@ Codacy can send more than one delivery for the same commit. Use this table to te | Your endpoint failed and Codacy retried | Same `X-Codacy-Delivery` | Ignore it if you already processed that ID | | The commit is on more than one enabled branch, or also belongs to a pull request | Same `commitSha`, different `target.value` or `target.type` | Not duplicates. Use `target` to tell them apart | | The commit was reanalyzed | New `X-Codacy-Delivery` and a later `timestamp`, same `repository.name`, `target`, and `commitSha` | Keep the delivery with the latest `timestamp` | +| SCA ran on the commit | Same as a reanalysis. Nothing in the payload says the delivery comes from SCA | If your organization uses SCA, see the note below before you keep only the latest delivery | Deliveries that match on `repository.name`, `target.type`, `target.value`, `commitSha`, and `timestamp` are duplicates. To keep only the latest result for a commit, match on the first four and keep the delivery with the latest `timestamp`. Don't match on `commitSha` alone. If you share one URL between organizations, include `organization.id` in the match. +!!! important + If your organization uses SCA, review how your integration handles several deliveries for the same commit before you rely on webhook data. Besides the analysis of a commit, Codacy runs SCA on the head commit of the main branch of each repository with SCA enabled, and that run sends its own `quality.analysis.completed` delivery for the commit. The `status` of that delivery reflects only the SCA run, and nothing in the payload tells it apart from a reanalysis. If you keep the delivery with the latest `timestamp`, the SCA delivery can replace the result of the quality analysis. Use the [Codacy API](../../codacy-api/using-the-codacy-api.md) to look up the analysis results when the difference matters. + - Codacy resolves the host of your endpoint before every delivery. If the host doesn't resolve, or resolves to a private or local network address, Codacy drops the delivery without a retry. - Codacy drops a delivery that still fails after the last retry, and doesn't support delivery logs or resending deliveries yet. You can log deliveries on your own endpoint if you need a record, and use the Codacy API to get info from past analysis. - Deliveries can arrive out of order, for example when a retry delays one of them. Use `timestamp` to order deliveries for the same repository.