Skip to content

Webhooks

Learn about webhooks and how to use them with the Vercel platform.

A webhook is a trigger-based HTTP endpoint configured to receive HTTP POST requests via events. When an event happens, a webhook is sent to another third-party app, which can then take appropriate action.

Webhooks configured with Vercel can trigger a deployment when a specific event occurs. Vercel integrations receive platform events via webhooks.

Configurable webhooks are available in Beta on Pro and Enterprise plans

Vercel allows you to add a generic endpoint for events from your dashboard. Pro and Enterprise teams will be able to configure these webhooks at the account level.

Choose your team scope on the dashboard, and go to Settings ➞ Webhooks.

Select events for your webhooks to listen.

The configured webhook listens to one or more events before it triggers the function request. Vercel supports event selections from the following categories:

Configurable webhooks listen to the following deployment-based events:

  • Deployment Created: Listens for when any new deployment is initiated
  • Deployment Succeeded: Listens for a successful deployment
  • Deployment Error: Listens for any failed deployment
  • Deployment Cancelled: Listens for a canceled deployment due to any failure
Note: Project events are only available when "All Team Projects" is selected as the project scope.

Configurable webhooks listen to the following project-based events:

  • Project Created: Listens whenever a new project is created
  • Project Removed: Listens whenever any project is deleted from the team account

The events you select should depend on your use case and the workflow you want to implement.

Choose the scope of project(s) for webhooks.

After selecting the event types, choose the scope of team projects for which webhooks will listen for events.

Define the endpoint URL for the webhooks to listen.

The endpoint URL is the destination that triggers the events. All events are forwarded to this URL as a POST request. In case of an event, your webhook initiates an HTTP callback to this endpoint that you must configure to receive data. In order to be accessible, make sure these endpoint URLs are public.

Once you have configured your webhook settings, click the "Create Webhook" button.

Confirmation to create the webhook.

This takes you to the secret key, which you can save for later use. After setting up the webhook URL, you are ready to receive payloads. Anybody can send you requests if they know the URL of your webhook.

It's recommended that you secure your webhooks by using the x-vercel-signature security header. See the API documentation to learn more about securing webhooks.

Click "Done" once you are ready.

Once created, you can view all your new and existing webhooks under the Webhooks section of the dashboard. This includes a complete summary of the webhooks configured with your Vercel account. If you want to remove any webhook, click the cross icon next to the webhook. While in beta, you can create and use up to 20 custom webhooks at one time.

Webhooks can also be created via Integrations. When creating a new integration, you can add webhooks using the Integration Console. Inside your Integration's settings page locate the text field for setting the webhook URL. This is where you should add the HTTP endpoint to listen for events. Next, you can select one or more of these checkboxes to specify which events to listen to.

Specifying the webhook URL and events to listen to.

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

webhook-payload
  "id": <eventId>,
  "type": <event-type>,
  "createdAt": <javascript-timestamp>,
  "payload": <payload for the event>,
  "region": <RegionId>,

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