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.
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.
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.
To get started, visit the Integration Console and click the Create button.
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.
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:
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:
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
- Next, add
MONGO_URL=@mongo_url_for_my_dbfor the projects where
Environment variables created by integrations will be displayed in the Project Settings with the logo of the integration that created them.
See the following API reference documentation for how to utilize it:
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.
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:
nullif the user does not belong to a team
Take a look at this example integration to learn more about how Delete Hooks work.
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.