Introduction

Vercel Integrations

Vercel Integrations introduce a way to extend the capabilities of Vercel and to connect with any platform.

The following are just some of the things you can do with Vercel Integrations:

  • Configure third-party services such as event tracking, error tracking, and performance monitoring.
  • Add databases into deployments with just a few clicks.
  • Gain complete access to the Vercel API.
  • Create mashup apps by connecting multiple different services of your choosing.
Note: This page is dedicated to explaining what Integrations are and how you can develop your own. To install an Integration instead, go to the Integrations Marketplace.

Why Build or Use an Integration?

Integrations are perfect for you if you want to pair Vercel's functionality with your service to increase productivity by removing configuration overhead for the user.

An example of this is the Sentry Integration which connects Vercel Projects to Sentry Projects. It also automatically sets up all required Environment Variables for your selected Vercel Projects.

Many more Integrations that work similarly can be created using the Vercel Integrations API with the Vercel API and any external service with an API.

What Makes an Integration?

Before you start building your first Integration, you'll need be able to create an HTTP endpoint on your system (the Redirect URL) that will:

  • Exchange a code for a Vercel API access token.
  • Render a responsive user interface inside a popup window during installation.
  • Allow users to provision a new project or connect existing projects in your system with their Vercel Projects.
  • Upon completion, redirect the user back to Vercel.

With Vercel Integrations you have opportunity to dramatically simplify the process of integrating your service with Vercel Projects so the user can focus on creating features instead of dealing with configurations.

Example Integration

To learn how to create your own integration, we've created an Example Integration. This example illustrates fundamental concepts like accessing and consuming the Vercel API.

Creating your Integration

To get started, visit the Integration Console and click the Create button.

Fill out the form by adding information such as Name, Descriptions, Logo and Media content.

Integration settings

In addition to the mentioned fields, there are three important settings you have to set for your integration.

Redirect URL

This URL should point to your site that will serve the UI during installation and calls the Vercel API. See Ways your Integration can be installed to learn which parameters are available during installation.

Note: For local development and testing, you can specify a URL on localhost.

Webhook URL

With your integration, you are able to listen for events on the Vercel Platform via Webhooks. See the Webhooks section to learn more.

Configuration URL

To allow the user to configure an installed integration, you can specify a Configuration URL. This URL is used for the Configure Button on each Configuration page. Clicking this button will redirect the user to your specified URL with a configurationId query parameter. See Interacting with Configurations to learn more.

Note: If you don't specify a Configuration URL, all users will see a Website button instead of a Configure button at the top of the configuration page. The Website button links to the website URL you specified on integration settings.

View Created Integration

Once you have created your Integration, you can see it listed on the Integrations Developer Console.

Inside your Integration, you can click the View In Marketplace button to see it in the marketplace.

Clicking this button will take you to the Public URL for your Integration. This URL can be shared with anyone who wishes to install and use your Integration.

The Public URL has the following format:

https://vercel.com/integrations/:slug
Note: Your Integration won't be visible on the Integrations Marketplace until you've submitted it for Review.

Best Practices

To provide the best experience for the user, we've outlined a few characteristics of a successful integration:

Good Marketing Content

Provide a high resolution logo, together with images having the aspect ratio of 3:2. Write a description of what your integration does and highlight the benefits the user will get.

Fast Installation Process

Upon arriving the Redirect URL, users should be able to complete installation as quickly as possible. Minimize the number of clicks and required inputs.

One idea to increase conversion might be to allow users to try out the integration without an account and claim their account later.

No Escape Hatches during Installation

Avoid displaying unnecessary UI elements such as the navigation bar used in the rest of your application; they will increase the chance of users exiting the flow.

Useful Configuration URL

Once the integration is installed, users would most likely want also to reconfigure it or see more details. Therefore, you should provide a Configuration URL that redirects the user to the Integration configuration page on your site.

Submitting for Review

If your integration is ready for all users, you can submit it for review. This review is required to be listed on the Integrations Marketplace, as well as to remove the review notice on your public integration page.

During the review, we take a look at your integration and verify that it works correctly and is following our Best Practices.

Please make sure you include all necessary information and links like Deploy Buttons for example - if you support them.

Installing your Integration

Once you've created your integration, it's ready to be installed. Each installation (also known as Configuration) is made under a certain scope.

Permissons

Each time a user installs an integration, we show the scope selection modal.

Inside this modal, the user can set two things:

  1. Which scope to install the integration (e.g. personal account or team).
  2. Which projects the integration has access to (e.g. all projects or a subset).
Note: This modal is shown when installing through the marketplace or the OAuth2 flow, but not through the Deploy Button. See Deploy Button for more details.

Ways your Integration can be installed

There are three ways an integration can be installed:

Marketplace

Vercel’s Integrations Marketplace is the most common way users install an integration.

Users can install an integration by clicking the "Add" button on the integration page. Clicking "Add" will show the scope selection modal, followed by the project selection modal. Then, the user proceeds to a popup page with your defined Redirect URL.

The Redirect URL should display a page that allows the user to setup the integration on your side. Once you finished, you redirect the user to the provided next URL. Redirecting to the next URL will close the popup window and the user can proceed with the flow.

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

Name
Definition
Example
code
The code you received.
jMIukZ1DBCKXHje3X14BCkU0
teamId
The ID of the team (only if a team is selected).
team_LLHUOMOoDlqOp8wPE4kFo9pE
configurationId
The ID of the configuration.
icfg_6uKSUQ359QCbPfECTAY9murE
next
Encoded URL to redirect to, once the installation process on your side is finished.
https%3A%2F%2Fvercel.com%2F...

OAuth2

The OAuth Flow is useful if you're building a mobile app or wish to start the installation flow from your side instead of from the marketplace. See our OAuth2 documentation for more details.

Instead of a popup with your Redirect URL, we redirect the user in the current window to the defined Redirect URL after the user selects an account in the scope selection modal.

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

Name
Definition
Example
code
The code you received.
jMIukZ1DBCKXHje3X14BCkU0
state
Random string to be passed back upon completion. It is used to protect against CSRF attacks.
xyzABC123

Deploy Button

When creating a Deploy Button to create projects based on a Git repository, you're able to specify required integrations.

If integration ids are specified on the deploy button, we show a list of required integrations during the flow. Each integration has an Install button that opens up a popup with the Redirect URL.

The Redirect URL should display a page that allows the user to setup the integration on your side. Once you finished, you redirect the user to the provided next URL. Redirecting to the next URL will close the popup window and the user can proceed with the flow.

Note: During the Deploy Button flow, we don't show a scope and project selection. The created configuration has access to the newly created project only.

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

Name
Definition
Example
code
The code you received.
jMIukZ1DBCKXHje3X14BCkU0
teamId
The ID of the team (only if a team is selected).
team_LLHUOMOoDlqOp8wPE4kFo9pE
configurationId
The ID of the configuration.
icfg_6uKSUQ359QCbPfECTAY9murE
next
Encoded URL to redirect to, once the installation process on your side is finished.
https%3A%2F%2Fvercel.com%2F...
currentProjectId
The ID of the created project.
QmXGTs7mvAMMC7WW5ebrM33qKG32QK3h4vmQMjmY
external-id
Reference of your choice. See External ID for more details.
1284210
Note: By using the currentProjectId parameter, you can skip the step of asking the user to choose which Vercel project to install the integration to.

Using the Vercel API

Getting an Access Token

Each time the user installs your Integration, we redirect to your defined Redirect URL. Since there are several ways of installing an integration, we attach different query parameters.

Whichever way the integration gets installed, you'll always get the code parameter. This code is temporary valid and can be only exchanged once for an (long lived) access token.

To learn more this exchange, visit our API Documentation about exchanging code for an access token.

Knowing the Scope of your Access Token

Since integrations are always installed on a certain scope, they have limited permissions.

Make sure you append the teamId query parameter to each API request, if your integration is installed on a team. See Accessing Resources Owned by a Team for more details.

The response of your code exchange request also includes a team_id property. If team_id has a value, you know that this integration was installed on a team.

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:

Webhooks

You can subscribe to certain events that are going to be published via Webhooks. There are a variety of use-cases for Webhooks. For example, cleaning up resources after someone removes your Integration.

Setting Up

The Webhook is a HTTP endpoint which is configured to receive HTTP POST requests. After you create the endpoint in your app, you can add it to the Integration via the Integration Console.

Inside your Integration's configuration page, there is a text field for setting the Webhook URL. This is where you should add the HTTP endpoint mentioned above.

Take a look at all available events to learn more about webhooks and payloads.

HTTP Response

You should consider this HTTP request to be an event. Once you receive the request, you should schedule a task for your action.

This request has a timeout of 30 seconds. That means, if a 2XX HTTP response is not received within 30 seconds, the request will be aborted.

Delivery Attempts and Retries

If your HTTP endpoint does not respond with a 2XX HTTP status code, we attempt to deliver the webhook event up to 24 hours with an exponential back off. Events that could not be delivered within 24 hours will not be retried and will be discarded.