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.
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 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:
Explain the integration and how to use it. Also explain the defaults and how to override them.
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.
Like all assets, it will appear in both light and dark mode.
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.
Before adding "Icons" and "Gallery images" you need to make sure that the images follow the following dimensions and aspect ratios.
High resolution bitmap image, non-transparent PNG, minimum 256px
High resolution bitmap image, non-transparent PNG. Minimum 3 images, up to 5 can be uploaded. You can upload 1 video link too
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.
Integration title which appears on dashboard/marketing pages also, accompanied by the Integration Icon.
Integration tagline on the Marketplace card, and the Integrations overview in the dashboard.
Name of the Integration Owner, generally a legal name.
Predefined category helping developers find an integration easily. E.g. Performance, Analytics, CMS, etc.
Link to the Developer's site.
Link to the Integration documentation.
Long description of the integration.
Additional steps to install or configure your integrations. Include environment variables and their purpose. Use markdown for links or code snippets.
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.
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
403HTTP status code and a
- We continue to send
integration-configuration-removedwebhooks, 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
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 creating integrations the following scopes can be updated within the Integration Console:
Interact with the installation of your integration
Interact with deployments
Verify deployments with Checks
Access project details and settings
Create and manage environment variables
Access team details
Get information about the current user
Create and manage log drains to forward logs
Manage and interact with domains and certificates
Interact with an installation of your integration.
Interact with deployments.
Verify deployments with Checks.
Access project details and settings.
Create and manage environment variables.
Get information about the current user.
Create and manage log drains to forward logs.
Manage and interact with domains and certificates.
As the Vercel API evolves, you'll need to update your scopes based on your integration's endpoint usage.
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.
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
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.