Introduction

Start building your Vercel integrations. These additional details make it easy to add extended functionality and features to your integrations.

Installing

Query parameters

There are three different ways to install your integration. And with every installation method, you can pass in query parameters to the Redirect URL to customize the installation.

Marketplace

When installing an integration via the Marketplace, the Redirect URL displays a page that allows a user to setup the integration on your side. Once finished, redirect the user to the provided next URL that will close the popup window and the user can proceed with the flow.

These are the query parameters attached to the Redirect URL:

External

With External installation, you can pass the state query parameter:

Key
Required
Description
Example
state
No
Random string to be passed back upon completion. It is used to protect against CSRF attacks.
xyzABC123

With the Redirect URL, you can use the following query parameters:

Deploy Button

When installing via Deploy Button, the Redirect URL displays a page that allows you to setup the integration on your side. Once finished, you redirect the user to the provided next URL which will close the popup window and the user can proceed with the flow.

These are the query parameters we attach to the Redirect URL:

Uninstalling an Integration

You can manage your installed Integrations. In your Vercel Dashboard, go to the "Integrations" tab, and select an Integration you’ve installed. You can manage which projects the installed Integration has access to.

Review Guidelines

Here are the review guidelines so you can make sure your integration is ready to be listed on the marketplace.

Technical specs

Installation flow (required)

The installation of the integration is a critical component of the developer experience that must cater all the different types of developers. While deciding the installation flow you should consider the following:

Other than Installation flow, which is an important component of the developer experience, you should also consider adding the following specs too.

Design specs

The design review specs include properties for Icon and Gallery Images.

Icon (required)

The image displayed in a circle, that appears throughout the dashboard and marketing pages.

Gallery images (required)

A collection of images displayed on the carousel at the top of your marketplace listing. We require at least 1 image but you can add up to 5 images.

Assets dimensions

Before adding "Icons" and "Gallery images" you need to make sure that the images follow the following dimensions and aspect ratios.

Content specs

Defining the content specs helps you create the main cover page of your integration. On the marketplace listing, the cover page looks like this.

For each of these details there are a set of specs that you need to take care of before submitting an integration for review.

Once your integration passes all the review checks it'll appear on the main Integrations Marketplace.

Using the Vercel API

Exchange code for Access Token

You can exchange the code parameter for an Access Token using the following API endpoint:

POST https://api.vercel.com/v2/oauth/access_token

Pass the following values to request body in the form of application/x-www-form-urlencoded.

Interacting with Configurations

Each installation of your integration is stored and tracked as a configuration.

Sometimes it makes sense to fetch the configuration in order to get more insights about the current scope or the projects your integration has access to.

To see which endpoints are available, visit our API Documentation about Configurations.

Interacting with Vercel Projects

Deployments made with Vercel are grouped into Projects. This means that each deployment is assigned a name and is grouped into a project with other deployments using that same name.

Using the Vercel API, you can modify Projects that the Integration has access to. Here are some examples:

Modifying Environment Variables on a Project

When building a Vercel Integration, you may want to expose an API token or a configuration URL for deployments within a Project.

You can do so by Creating a Project Environment Variable using the API.

Note: Environment Variables created by an Integration will display the Integration's logo.

Using the Vercel API

See the following API reference documentation for how to utilize it:

Common Errors

When using the Vercel API with Integrations, you might come across some errors which you can address immediately.

CORS issues

To avoid CORS issues, make sure you only interact with the Vercel API on the server side.

Since the token grants access to resources of the Team or Personal Account, you should never expose it on the client side.

403 Forbidden responses

Ensure you are not missing the teamId query parameter. teamId is required if the integration installation is for a Team. See Knowing the Scope of Your Access Token for more details.

Using the Checks API

Creating Checks

Checks are powered by Integrations, which allow you to connect any third-party service of your choice with Vercel. Checks should listen to three different event types during deployment.

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

Rerunning Checks

If you are opted into the deployment-checks-re-requested 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-checks-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.

Upgrading Your Integration

You should upgrade your integration if you are using any of the following scenarios.

Use generic Webhooks

Use generic Webhooks instead of Webhooks APIs and Delete Hooks. As announced on this Changelog post, you can now specify a generic Webhook URL in your Integration settings.

The Vercel API to list, create, and delete Webhooks has been removed. There's also no support for Delete Hooks which are notified on Integration Configuration removal. If you have been using either or both features, you need to update your Integration.

Use External Flow

If your Integration is using the OAuth2 installation flow, you should use the External installation flow instead. By using the External flow, users will be able to choose which Vercel scope (Personal Account or Team) to install your Integration to.

Use your own UI

UI Hooks is a deprecated feature that allowed you to create custom configuration UI for your Integration inside the Vercel dashboard. If your Integration is using UI Hooks, you should build your own UI instead.

Legacy Integrations

Integration that use UI Hooks are now fully sunsetted. Users are not able to install them anymore.

If you are using a Legacy Integrations, it's recommended finding an updated Integration on the Integrations Marketplace. If adequate replacement is not available, contact the integration developer for more information.

If you are the developer of a legacy integration, please follow these instructions to upgrade your integration.

currentProjectId in Deploy Button

If your Integration is not using currentProjectId to determine the target project for the Deploy Button flow, please use it. Here’s the documentation.

Single installation per scope

If your Integration assumes that it can be installed multiple times in a Vercel scope (personal account or team), read the following so that it can support single installation per scope for each flow:

Latest API for Environment Variables

If your Integration is setting Environment Variables, please make sure to use type=encrypted with the latest version (v7) of the API when creating Environment Variables for a Project.

Note: Creating project secrets is not required anymore and will be deprecated in the near future.