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.

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.

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.

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

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.

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.

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

If the Integration has not been installed in the selected scope, 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:

If already installed in the selected scope

When installing from the Marketplace, your Integration can only be installed once per scope (personal account or team). If the user chooses a scope to which the Integration is already installed, the user proceeds to the Integration Configuration page.

External

The External 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. Redirect the user to the following URL to start the installation process from your side:

https://vercel.com/integrations/:slug/new

slug should be your Integration's slug. You may pass the state query parameter:

As with installing from the Marketplace, the user will be asked to select a Vercel scope (Personal Account or Team) to install this Integration. Then, we redirect the user in the current window to the defined Redirect URL (instead of in a popup window).

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

If already installed in the selected scope

When installing from the External flow, your Integration can only be installed once per scope (personal account or team). If the user chooses a scope to which the Integration is already installed, a new code is generated, and the user proceeds to the Redirect URL. No new Configuration is created.

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.

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

If already installed in the selected scope

The Redirect URL will be called with the most recent configurationId if the Integration is already installed in the selected scope during the Deploy Button flow. Please make sure to store configurationId along with an access token such that, if an existing configurationId was passed, you can retrieve the corresponding access token.

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 valid for 30 minutes and can be only exchanged once for an (long lived) access token.

Exchanging the Code for an Access Token

Exchange the code for an access token using the following API:

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.

You'll receive a JSON response containing an access_token:

Example Request

curl -X POST https://api.vercel.com/v2/oauth/access_token \
 -d "client_id=oac_s4cllbR9Ao8307IDSkluOQBS&client_secret=EOBPvZuBYAtb3SbYo8H1iWFP&code=jMIukZ1DBCKXHje3X14BCkU0&redirect_uri=https://example.com/oauth" \
 -H "Content-Type: application/x-www-form-urlencoded"

Example Response

{
  "access_token": "xEbuzM1ZAJ46afITQlYqH605"
}

Using Access Token

The access token allows you to make requests to the Vercel API by providing the token in the Authorization header.

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 may include 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.

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

Webhooks

You can subscribe to certain events that are going to be published via Webhooks. There are a variety of use-cases for Webhooks, such as 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 settings page, there is a text field for setting the Webhook URL. This is where you should add the HTTP endpoint mentioned above. You can toggle checkboxes to specify which events to listen to.

Specifying the Webhook URL and events to listen to.

Events

The webhook URL receives a HTTP POST request with a JSON payload for each event. All the events has the following format:

{
  "id": <eventId>,
  "type": <event-type>,
  "clientId": <clientId>,
  "createdAt": <javascript-timestamp>,
  "payload": <payload for the event>,
  "ownerId": <ownerId>,
  "teamId": <teamId>,
  "userId": <userId>,
  "webhookId": <webhookId>
}

Here's a list of supported event types and their payload:

deployment

Occurs whenever a Deployment is created.

deployment-ready

Occurs whenever a Deployment is ready.

deployment-error

Occurs whenever a Deployment has failed.

project-created

Occurs whenever a Project has been created.

project-removed

Occurs whenever a Project has been removed.

integration-configuration-removed

Occurs whenever an Integration has been removed.

integration-configuration-permission-updated

Occurs whenever the user changes the permission for an Integration.

domain-created

Occurs whenever a Domain has been created.

Securing Webhooks

Once your server is configured to receive payloads, it will listen for any payload sent to the endpoint you configured. By knowing the URL of your webhook, anybody can send you requests. It is therefore recommend to check whether the requests are coming from Vercel or not.

The recommended method to check is to use the x-vercel-signature security header you receive with each request. The value of this header corresponds to the sha1 of the payload body using your client secret.

For example, you can validate a webhook message as follows:

const crypto = require('crypto');
const { send } = require('micro');

module.exports = (req, res) => {
  const payload = await json(req);

  if (!verifySignature(req, payload)) {
    return send(res, 403, {
      code: `invalid_signature`,
      error: `signature didn't match`
    });
  }

  // Process the payload
};

function verifySignature(req, payload) {
  const signature = crypto.createHmac('sha1', process.env.OAUTH2_SECRET)
    .update(payload)
    .digest('hex');
  return signature === req.headers['x-vercel-signature'];
}

Example on how to validate a webhook message.

You can compute the signature using a HMAC hexdigest from the secret token of OAuth2 and request body, then compare it with the value of the x-vercel-signature header to validate the payload.

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.

Upgrading Your Integration

If your Integration is using outdated features on the Vercel Platform, follow the guidelines below to upgrade your Integration and use the latest features.

Use generic Webhooks instead of Webhooks APIs and Delete Hooks

As announced on this Changelog post on April 20th, 2021, you can now specify a generic Webhook URL in your Integration settings.

The Vercel API to list, create, and delete Webhooks is deprecated and will be removed. We also no longer support 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 you were using Webhooks APIs but not a Delete Hook

Check your code to see if you are listing, creating, or deleting Webhooks via the Vercel API. These Webhooks APIs are deprecated and will be removed on August 20th, 2021.

If you were creating a Webhook by sending a POST request to /v1/integrations/webhooks, these requests should be removed:

1. Copy the Webhook URL that was specified via the Webhooks API and set it as the Webhook URL in your Integration settings.
2. Turn on checkboxes corresponding to the event types that were previously specified via the API (Deployment Created, Deployment Ready, or Deployment Error).

You should also remove GET and DELETE requests to /v1/integrations/webhooks as well.

If you were using a Delete Hook but not Webhooks APIs

Check your Integration settings. If a Delete Hook URL was set, it is now set as a generic Webhook URL, and "Integration Removed" is turned on.

At the moment, the Integration Removed event is sent as two events (a POST request and a DELETE request). The DELETE requests will no longer be sent starting August 20th, 2021.

To update, modify your existing Delete Hook endpoint such that:

• It accepts a POST request instead of a DELETE request. If it receives a DELETE request, it should be ignored.
• It accepts a request body that has the Webhook Event JSON format, which is of type integration-configuration-removed and contains a payload key containing a configuration object as explained here.

If you were using both Webhook APIs and a Delete Hook

You need to consolidate both endpoints (a Webhook URL and a Delete Hook URL) into a single Webhook URL that can handle both types of events (deployment related events and integration-configuration-removed events).

Use the External Flow instead of OAuth2

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.

Replace the OAuth2 entrypoint:

https://vercel.com/oauth/authorize?client_id=…&state=…

With this URL, using your Integration slug:

https://vercel.com/integrations/:slug/new?state=…

Learn more about the External flow here.

Use your own UI instead of UI Hooks

If your Integration is using UI Hooks, you should build your own UI instead.

Remove UI Hooks code

If you are using UI Hooks, you’d have installed the @vercel/integration-utils package. Remove this package and all the code referencing it.

Build your own UI

Build your own UI by following our guide and our example Integration.

Once that's done, specify the Redirect URL and remove the UI Hooks URL in your Integration settings.

Use currentProjectId in the Deploy Button flow

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

Assume 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

Use latest API version for adding Environment Variables to Projects

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