Start building your Vercel integrations. These additional details make it easy to add extended functionality and features to your integrations.
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.
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:
With External installation, you can pass the
state query parameter:
Random string to be passed back upon completion. It is used to protect against CSRF attacks.
With the Redirect URL, you can use the following query parameters:
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:
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.
Here are the review guidelines so you can make sure your integration is ready to be listed on the marketplace.
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.
The design review specs include properties for Icon and Gallery Images.
The image displayed in a circle, that appears throughout the dashboard and marketing pages.
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.
Before adding "Icons" and "Gallery images" you need to make sure that the images follow the following dimensions and aspect ratios.
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.
You can exchange the
code parameter for an Access Token using the following API endpoint:
Pass the following values to request body in the form of
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.
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:
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.
See the following API reference documentation for how to utilize it:
When using the Vercel API with Integrations, you might come across some errors which you can address immediately.
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.
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:
If you are opted into the
webhook, then you will have the option to specify whether a check supports being re-requested when creating a check by providing the
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
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:
You can then use your existing logic to run a check and update the status.
You should upgrade your integration if you are using any of the following scenarios.
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.
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.
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.
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.
If your Integration is not using
currentProjectId to determine the target project for the Deploy Button flow, please use it. Here’s the documentation.
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:
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.