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 other services.

An example of this is the Google Cloud Integration which connects projects on Vercel to Google Cloud Platform projects where you can run Vercel deployments as CRON jobs through the Google Cloud Scheduler, create and connect to MySQL/PostgreSQL databases with Google Cloud SQL, and much more that would be a lot harder without an Integration.

Many more Integrations that help users in similar ways can be created using the Vercel Integrations API in partnership 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 OAuth2 access token.
  • Render a responsive user interface - possibly inside of a popup window.
  • Allow users to provision new, 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.

Creating Your Integration

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

Creating an Integration using the Integrations dashboard.

Complete the form and at the end you will find a field named Redirect URL.

This is the HTTP handler on your site that will serve the Integration UI and call any Vercel APIs.

Note: For local development and testing you can use http://localhost:3000.

Marketplace URL

Once you create 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

An example Public URL for an Integration.

Project Level APIs

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.

Users can deploy projects for any type of app. For example, there could be:

  • A project for a marketing website.
  • A project for a backend API.
  • A project for an admin dashboard.
  • A project with all three in a monorepo.

Using a Vercel Integration, you can modify configuration for whole projects, for which we expose a set of API endpoints:

Project-Based Environment Variables

When building a Vercel Integration, you may want to expose an API secret or a configuration URL for deployments within a project.

For example, say you want to expose the MONGO_URL environment variable; the following would be the process to do so:

  • Create a secret to store the value for MONGO_URL (This is an account wide operation). For this example, we'll assume the value for the secret key is mongo_url_for_my_db.
  • Next, add MONGO_URL=@mongo_url_for_my_db for the projects where MONGO_URL is needed.
Note: The pattern is to create a secret once per account then use it many times with different projects.

Environment variables created by integrations will be displayed in the Project Settings with the logo of the integration that created them.

Using the API directly

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

Delete Hooks

When the user removes your Integration you will receive a notification via Delete Hooks. There are a variety of use-cases for Delete Hooks, for example, cleaning up resources created by the configuration.

Setting Up

The Delete Hook is a HTTP endpoint which is configured to receive HTTP DELETE 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 an input to set the Delete Hook URL. This is where you should add the HTTP endpoint mentioned above.

With the Delete Hook URL set, when a user removes your Integration, a HTTP DELETE request will be sent to the defined endpoint. The payload your delete endpoint receives is a JSON encoded HTTP body with the following fields:

  • configurationId
  • userId
  • teamId - null if the user does not belong to a team

Take a look at this example integration to learn more about how Delete Hooks work.

HTTP Response

You should consider this HTTP request as an event. Once you receive the request, you should schedule a task for the cleanup action.

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