Reference
4 min read

Anatomy of the Checks API

Learn how to create your own Checks with Vercel Integrations. You can build your own Integration in order to register any arbitrary Check for your deployments.
Table of Contents

Checks API extends the build and deploy process once your deployment is ready. Each check behaves like a webhook that triggers specific events, such as deployment.created, deployment.ready, and deployment.succeeded. The test are verified before domains are assigned.

To learn more, see the Supported Webhooks Events docs.

The workflow for registering and running a check is as follows:

  1. A check is created after the deployment.created event
  2. When the deployment.ready event triggers, the check updates its status to running
  3. When the check is finished, the status updates to completed

If a check is "rerequestable", your integration users get an option to rerequest and rerun the failing checks.

Depending on the type, checks can block the domain assignment stage of deployments.

  • Blocking Checks: Prevents a successful deployment and returns a conclusion with a state value of canceled or failed. For example, a Core Check returning a 404 error results in a failed conclusion for a deployment
  • Non-blocking Checks: Return test results with a successful deployment regardless of the conclusion

A blocking check with a failed state is configured by the developer (and not the integration).

Checks are always associated with a specific deployment that is tested and validated.

AttributesFormatPurpose
blockingBooleanTells Vercel if this check needs to block the deployment
nameStringName of the check
detailsUrlString (optional)URL to display in the Vercel dashboard
externalIDString (optional)ID used for external use
pathString (optional)Path of the page that is being checked
rerequestableBoolean (optional)Tells Vercel if the check can rerun. Users can trigger a deployment.check-rerequested webhook, through a button on the deployment page
conclusionString (optional)The result of a running check. For blocking checks the values can be canceled, failed, neutral, succeeded, skipped. canceled and failed
statusString (optional)Tells Vercel the status of the check with values: running and completed
outputObject (optional)Details about the result of the check. Vercel uses this data to display actionable information for developers. This helps them debug failed checks

The check gets a stale status if there is no status update for more than one hour (status = registered). The same applies if the check is running (status = running) for more than five minutes.

ResponseFormatPurpose
statusStringThe status of the check. It expects specific values like running or completed
stateStringTells the current state of the connection
connectedAtNumberTimestamp (in milliseconds) of when the configuration was connected
typeStringName of the integrator performing the check
StatusOutcome
200Success
400One of the provided values in the request body is invalid, OR one of the provided values in the request query is invalid
403The provided token is not from an OAuth2 client OR you do not have permission to access this resource OR the API token doesn't have permission to perform the request
404The check was not found OR the deployment was not found
413The output provided is too large

The output property can store any data like Web Vitals and Virtual Experience Score. It is defined under a metrics field:

KeyTypeDescription
TBTMapThe Total Blocking Time, measured by the check
LCPMapThe Largest Contentful Paint, measured by the check
FCPMapThe First Contentful Paint, measured by the check
CLSMapThe Cumulative Layout Shift, measured by the check
virtualExperienceScoreMapThe overall Virtual Experience Score measured by the check

Each of these keys has the following properties:

KeyTypeDescription
valueFloatThe value measured for a particular metric, in milliseconds. For virtualExperienceScore this value is the percentage between 0 and 1
previousValueFloatA previous value for comparison purposes
sourceEnumweb-vitals

metrics makes Web Vitals visible on checks. It is defined inside output as follows:

checks-metrics.json
{
  "path": "/",
  "output": {
    "metrics": {
        "FCP": {
          "value": 1200,
          "previousValue": 1400,
          "source": "web-vitals"
        }
        "LCP": {
          "value": 1200,
          "previousValue": 1400,
          "source": "web-vitals"
        },
        "CLS": {
          "value": 1200,
          "previousValue": 1400,
          "source": "web-vitals"
        },
        "TBT": {
          "value": 1200,
          "previousValue": 1400,
          "source": "web-vitals"
        }
      }
    }
  }
}

All fields are required except previousValue. If previousValue is present, the delta will be shown.

A check can be "rerequested" using the deployment.check-rerequested webhook. Add the rerequestable attribute, and you can rerequest failed checks.

A rerequested check triggers thedeployment.check-rerequested webhook. It updates the check status to running and resets the conclusion, detailsUrl, externalId, and output fields.

You can "Skip" to stop and ignore check results without affecting the alias assignment. You cannot skip active checks. They continue running until built successfully, and assign domains as the last step.

For "Running Checks", only the Automatic Deployment URL is available. Automatic Branch URL and Custom Domains will apply once the checks finish.

Checks may take different times to run. Each integrator determines the running order of the checks. While Vercel REST API determines the order of check results.

When Checks API begins running on your deployment, the status is set to running. Once it gets a conclusion, the status updates to completed. This results in a successful deployment.

However, your deployment will fail if the conclusion updates to one of the following values:

Conclusionblocking=true
 canceledYes
 failedYes
 neutralNo
 succeededNo
 skippedNo
Last updated on June 19, 2024