Webhooks#

This feature is only available on Business plan

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.

Adding a webhook endpoint#

Only an organization admin or organization manager can add a webhook endpoint. An organization has a maximum of 10 webhook endpoints.

To add a webhook endpoint:

Open your organization Integrations, page Webhooks (listed under Developer tools).
Click Add endpoint.
Enter the HTTPS URL that should receive the webhook deliveries in Payload URL, then click Add endpoint. Codacy only posts to https:// URLs that are reachable from the public internet.

Codacy generates a signing secret for the new endpoint and shows it once, in a card above the list of endpoints. Click the copy button to copy the secret and store it somewhere safe — you need it to verify deliveries, and Codacy doesn't show it again. Dismiss stays disabled until you copy the secret.

Warning

Codacy doesn't let you view or regenerate the secret of an existing endpoint. If you lose it, delete the endpoint and add it again to get a new one.

If your organization doesn't have access to webhooks yet, the Webhooks page shows an upgrade prompt instead. Talk to us about upgrading.

Managing webhook endpoints#

The Webhooks page lists the endpoints configured for your organization.

You can't edit an existing endpoint or rotate its secret — delete the endpoint and add a new one instead. To delete an endpoint, click the Delete icon on its row and confirm. Deleting an endpoint stops Codacy from posting to it immediately and destroys its signing secret.

Once the organization reaches 10 endpoints, Add endpoint is disabled. Delete an endpoint to add another one.

Managing endpoints with the API#

You can also add, list, and delete webhook endpoints by calling the Codacy API with an account API token. The endpoints you create through the API are the same ones the Webhooks page shows.

Call createWebhookEndpoint with the HTTPS URL that should receive the webhook deliveries:

curl -X POST 'https://api.codacy.com/api/v3/organizations/gh/my-organization/integrations/webhooks' \
     -H 'api-token: <your account API token>' \
     -H 'Content-Type: application/json' \
     -d '{"url": "https://example.com/webhooks/codacy"}'

Codacy returns the signing secret once, in the response:

{
  "id": "80f64371-e6bc-4d9b-b022-7c873cc5e39f",
  "url": "https://example.com/webhooks/codacy",
  "createdAt": "2026-09-17T09:10:00Z",
  "secret": "3n8fVhZ2k9m1QpXeYtR7wLdCsUbGjNoA"
}

If your organization doesn't have webhooks enabled, this request fails with an HTTP 403 error.

Call listWebhookEndpoints to see the endpoints configured for your organization:

curl -X GET 'https://api.codacy.com/api/v3/organizations/gh/my-organization/integrations/webhooks' \
     -H 'api-token: <your account API token>'

{
  "data": [
    {
      "id": "80f64371-e6bc-4d9b-b022-7c873cc5e39f",
      "url": "https://example.com/webhooks/codacy",
      "createdAt": "2026-09-17T09:10:00Z"
    }
  ],
  "count": 1,
  "limit": 10
}

Call deleteWebhookEndpoint with the endpoint's id to delete it:

curl -X DELETE 'https://api.codacy.com/api/v3/organizations/gh/my-organization/integrations/webhooks/80f64371-e6bc-4d9b-b022-7c873cc5e39f' \
     -H 'api-token: <your account API token>'

Events sent to your endpoint#

Codacy sends the quality.analysis.completed event to every webhook endpoint of your organization when:

A branch analysis finishes. Codacy finished analyzing the newest commit of an enabled branch. Only the newest commit on a branch triggers a delivery, and reanalyzing that commit sends a new delivery.
A pull request analysis finishes.

Codacy sends the event regardless of the analysis outcome, not only when it succeeds. Check the body's status field for the outcome.

Delivery payload#

Each delivery is an HTTP POST request with a JSON body and these headers:

Header	Description
`X-Codacy-Event`	The event type, always `quality.analysis.completed`.
`X-Codacy-Delivery`	A UUID that uniquely identifies this delivery. A reanalysis of the same commit generates a new UUID, but a retry of the same delivery reuses it — see delivery behavior.
`X-Codacy-Signature`	The HMAC-SHA256 signature of the request body, in the form `sha256=<hex-encoded hash>`.

The body identifies the organization, the repository, the commit, and either the branch or the pull request. It doesn't include the analysis results.

Branch analysis finished:

{
  "event": "quality.analysis.completed",
  "organization": { "provider": "gh" },
  "repository": { "name": "engine" },
  "target": { "type": "branch", "value": "master" },
  "commitSha": "a1b2c3d4e5f60718293a4b5c6d7e8f9012345678",
  "status": "success",
  "timestamp": "2025-09-17T23:00:00Z"
}

Pull request analysis finished:

{
  "event": "quality.analysis.completed",
  "organization": { "provider": "gh" },
  "repository": { "name": "engine" },
  "target": { "type": "pullRequest", "value": "464" },
  "commitSha": "a1b2c3d4e5f60718293a4b5c6d7e8f9012345678",
  "status": "success",
  "timestamp": "2025-09-17T23:00:00Z"
}

target.type is branch for a branch analysis or pullRequest for a pull request analysis. target.value is always a string — the branch name, or the pull request number.
organization.provider is the Git provider short code: gh for GitHub, gl for GitLab, or bb for Bitbucket.
status is success, partial_success, or failure — whether all, some, or none of the analysis tasks completed.
timestamp is when Codacy sent the delivery, as an ISO 8601 UTC timestamp to the second (2025-09-17T23:00:00Z). There's no separate timestamp header: the signature covers the whole body, so verify this field instead of a header if you need to reject stale deliveries.

Codacy doesn't include an issue list or a link to the analysis result in the payload. Use the Codacy API to look up the analysis details for the commit or pull request.

Verifying a delivery#

Verify that a delivery came from Codacy by recomputing its signature and comparing it to the X-Codacy-Signature header:

Compute the HMAC-SHA256 hash of the raw request body, using the endpoint's signing secret as the key.
Hex-encode the hash and prefix it with sha256=.
Compare the result to the X-Codacy-Signature header using a constant-time comparison, and reject the delivery if they don't match.
Optionally reject a delivery whose body timestamp is too old, to guard against a captured delivery being replayed.

Delivery behavior#

Codacy waits 10 seconds for your endpoint to respond. A 5xx response or a timeout is retried up to 2 more times with exponential backoff, waiting about 1 second before the first retry and about 5 seconds before the second, each with random jitter. A 4xx response drops the delivery immediately, without a retry.
A retry reuses the same X-Codacy-Delivery value as the original attempt, so treat retries with the same value as duplicates.
Codacy can also send more than one delivery for the same commit for other reasons, for example a reanalysis. Each of those deliveries has a distinct X-Codacy-Delivery value, so if you need to avoid processing the same commit twice, treat deliveries with the same commitSha as duplicates instead.
Codacy doesn't keep a delivery log or let you resend a delivery. Log deliveries on your own endpoint if you need a record of what Codacy sent.

Was this page helpful?

Your feedback helps us improve the documentation.

Edit this page on GitHub Contact support

Webhooks#

Adding a webhook endpoint#

Managing webhook endpoints#

Managing endpoints with the API#

Events sent to your endpoint#

Delivery payload#

Verifying a delivery#

Delivery behavior#

See also#

Was this page helpful?