Skip to content

Building your own Checks

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. This integration can be for your own use cases, or you can publish it to the Integration Marketplace, so that other Teams on Vercel can start using it.

Checks are powered by Integrations, which allow you to connect any third-party service of your choice with Vercel. Each Check works as a webhook and gets triggered on specific events: deployment.created, deployment-ready, and deployment.succeeded. Checks should listen to these event types during deployment.

The typical workflow for registering and running Checks looks like this:

  1. Create a Check after the deployment.created event was received.
  2. Update the Check by setting its status to running once you've received the deployment.ready event.
  3. After your Check has finished, update the check again with a conclusion — setting a conclusion sets the check status automatically to completed.

If a check is set as re-requestable, your integration users will see the option to re-request and re-run Checks that have failed.

You can store any arbitrary data, Web Vitals and a Virtual Experience Score through the output property of a Check. Passing certain properties along your data can be displayed in a more meaningful way.

To make web vital visible on Checks you need pass a metrics property inside output with the following format:

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"
        }
      }
    }
  }
}
Note: All fields are required except previousValue. If previousValue is present, the delta will be shown.

If you are opted into the deployment.check-rerequested webhook, then you will have the option to specify whether a check supports being re-requested when creating a check by providing the re-requestable property.

If a check is set as re-requestable, users will see the option to re-request Checks that have failed.

If the user clicks on a link to re-request a check, we will fire the deployment.check-rerequested webhook.

Once a check has been re-requested, you are able to update the check status back to running. This will reset the following fields as if the check was running for the first time: conclusion detailsUrl externalId output.

You can then use your existing logic to run a check and update the status.

All Vercel Integrations offer Checks. You can build your own Checks Integration in order to register any arbitrary Check for your Deployments.

This custom Check will work exclusively on your use cases. If you want other Teams to start using it, you need to get that listed on the marketplace.

E.g., if you'd like to perform Reliability or Performance Tests (including custom End-to-End-Tests) with Checks, Vercel recommends the Checkly Integration.

For every new Deployment, Vercel uses its source files to understand which parts of your app have changed and avoid compiling pages that have already been compiled in previous Deployments.

When building Vercel Integrations, you can actually decide how Checks act on different parts of your application with every Deployment.

This happens because Integrations provide their paths as a part of the Check's results.

An example of two Checks registered for two different pages.

Depending on which Integration you've added and how you've configured it, you might see different amounts of Checks appear for your Deployments. If one of your Deployment's pages isn't listed in the Checks, please refer to the settings of the third-party service you've integrated with.

Once a Check has begun running, it might choose to reveal a link on which you can view more details about its progress and/or its completion results:

The button for viewing more details of a particular Check.

As you can see, the link will be accessible from the right side of every Check if it is present, and will point you to an external page outside the Vercel dashboard, provided by the third-party service that you've integrated with.

If you've added an Integration to your Personal Account or a Team that supports Checks, the Integration will be notified every time a new Deployment is created.

It's up to the Integration to decide when to reveal a Check. Ideally, an Integration can register for a new Check before your Deployment reaches the "Running Checks" step.

Once your Deployment has reached the "Running Checks" stage, all the Integrations that registered Checks for the Deployment will be notified simultaneously, and will perform their particular actions on it.

Since different services might take different amounts of time to perform their actions, the results will likely arrive at non-identical times. Once all the Checks are performed, all the third-party services behind the Integrations will report results back to the platform.

When all the Checks have reported a result, the "Running Checks" step will be considered complete, and the Deployment will proceed to the finishing stage.

When the "Running Checks" step starts, only the Automatic Deployment URL will be available, which is therefore also the URL that Integrations use to perform their actions on your Deployment.

Other URLs like the Automatic Branch URL and Custom Domains defined for your Project will be applied after the step has finished.