Vercel allows you to enhance the platform's capabilities by creating and installing integrations with several third-party platforms and services. Start using Vercel Integrations by visiting the Vercel's Marketplace, which helps you extend and automate your workflow.

The details below simplify adding 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:

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 to all types of developers. While deciding the installation flow you should consider the following:

• New user flow (required): Developers should be able to create an account on your service while installing the integration
• Existing user flow (required): With existing accounts, developers should sign in as they install the integration. Also, make sure the forgotten password flow doesn't break the installation flow.
• Strong defaults (required): The installation flow should have minimal steps and have set defaults whenever possible
• Advanced settings (optional): Provide developers with the ability to override or expand settings when installing the integration

For the installation flow, you should consider adding the following specs:

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.

Like all assets, it will appear in both light and dark mode.

Gallery images (required)

These are a collection of images displayed on the carousel at the top of your marketplace listing. We require at least 3 images, but you can add up to 5. The images and text must be of high quality.

These gallery images will appear in both light and dark mode. Avoid long text, as it may not be legible on smaller screens.

Also consider the 20% safe zone around the edges of the image by placing the most important content of your images within the bounds. This will ensure that no information is cut when cropped.

Asset 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.

The following requirements are located in the integrations console.

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.

Disabled Integration Configurations

Please be aware that integration configurations can be disabled at any time when its owner leaves a team. When integration configurations are disabled:

• Any API requests will fail with a 403 HTTP status code and a code of integration_configuration_disabled
• We continue to send project-created, project-removed and integration-configuration-removed webhooks, as these will allow the integration configuration to operate correctly when re-activated. All other webhook delivery will be paused
• Log drains will not receive any logs

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.

Using the Vercel API

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

• Creating a Project Environment Variable
• Forwarding Logs using Log Drains

Scopes

When creating integrations the following scopes can be updated within the Integration Console:

Updating Scopes

As the Vercel API evolves, you'll need to update your scopes based on your integration's endpoint usage.

Confirming Scope changes.

Additions and upgrades always require a review and confirmation. To ensure this, every affected user and team owner will be informed via email to undergo this process. Please make sure you provide a meaningful, short, and descriptive note for your changes.

Scope removals and downgrades won't require user confirmation and will be applied immediately to confirmed scopes and pending requested scope changes.

Confirmed Scope Changes

User and Teams will always confirm all pending changes with one confirmation. That means that if you have requested new scopes multiple times over the past year, the users will see a summary of all pending changes with their respective provided note.

Once a user confirms these changes, scopes get directly applied to the installation. You will also get notified via the new integration-configuration-scope-change-confirmed event.

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:

• Marketplace flow
• External flow
• Deploy Button 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.