Get Started

Integrating with Coveralls

Coveralls Builds

The Web App


Get Help

API > Parallel Build Webhook



The Parallel Build Webhook is a webhook that closes a parallel build.*

  • Resource: Parallel Build (“Build”) (build)
  • Actions: POST
  • URI:
  • Data format: JSON
  • Authentication: Coveralls Repo Token
  • Full guide: This guide

Use Case for the Parallel Build Webhook

This webhook is useful for closing a parallel build when all of its jobs have completed.

Typical use case: A user configures their Coveralls Integration to handle a parallel build. Their CI build script runs and sends coverage reports in several, related jobs to Coveralls. When all jobs have been sent, the Coveralls Integration sends a request to the Parallel Build Webhook to close the build, which triggers a final, aggregate coverage calculation, completing the build and triggering status updates, PR comments or other types of coveralls notifications.

Example Request

Here’s an example POST request to the Parallel Build Webhook:

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{
      "payload": {    
          "build_num": "4193273239",    
          "status": "done"    
  }' \

Let’s break it down:

  • curl: The command-line tool we’re using to make the request.
  • -X POST: The HTTP method we’re using to make the request.
  • -H 'Content-Type: application/json': Header specifying JSON datatype.
  • The URL of the Parallel Build Webhook.
  • -d '{"payload":{"build_num":"4193273239","status":"done"}': The JSON data we’re sending with the request (aka. Payload). This is required.
  • ?repo_token=9DhgwUv9YiJjkm6PP4c6DxBgeUiXObJjK: The Coveralls Repo Token for the repo we’re closing the build for. This is required.
  • &carryforward=borrower,rates,webapp: The Carryforward Flags for the build we’re closing. This is optional.

Data Parameters

There are three (3) required and one (1) optional parameters for the Parallel Build Webhook:

Payload (Required)

The Payload JSON object—passed as payload—is required and must have the following properties:

    "payload": {
        "build_num": "4193273239",
        "status": "done"

Coveralls Repo Token (Required)

The Coveralls Repo Token—passed as the repo_token URL parameter—is required to authenticate the request.


Read more about the Coveralls Repo Token.

Carryforward Flags (Optional)

Carryforward Flags are optional and, when passed as the value for carryforward, can be used to instruct Coveralls to carry forward coverage report data from a previous build for any jobs that are missing from the current build.


Read more about Carryforward Flags.

All Parameters

Name Description Type
The secret token for your repository, found at the top of your Repo Page, or in Repo Settings, at Coveralls. String
carryforward String of comma-separated flag_names. Tells Coveralls to carry forward the last coverage report for any flag (job) in the list. String
The build number. Required to identify the build to be closed. This is the same build number that was used to create the build, which is the value passed for service_number in each parallel job. String
The status of the build. Required to close the build. The only valid value is "done". String


200 Success

Coveralls will respond with an HTTP 200 OK response if the request was successful, along with a JSON object containing "done":true, the URL to the finished build—and the number of jobs in it—at Coveralls.


Header: 200 OK
Body: {"done":true,"url":"","jobs":6}


Any other response code should be considered a failure and the response body will be set to the error text.


Header: 422 Unprocessable Entity
Body: {"error":"No build matching CI build number found"}


Any problems, questions or comments about this doc? Let us know.