Webhooks API Reference

Vercel Integrations allow you to subscribe to certain trigger-based events through webhooks. An example use-cases for webhooks might be cleaning up resources after someone removes your Integration.

The webhook payload is a JSON object with the following keys.

Occurs whenever a deployment is canceled.

Occurs when a user has requested for a check to be rerun after it failed.

Occurs whenever a deployment is created.

Occurs whenever a deployment has failed.

Occurs whenever a deployment is promoted.

Occurs whenever a deployment is successfully built and your integration has registered at least one check.

Occurs whenever a deployment is ready.

Occurs whenever a domain has been created.

Occurs whenever the user changes the project permission for an integration.

Occurs whenever an integration has been removed.

Occurs whenever the user confirms pending scope changes.

Occurs when an invoice was created and sent to the customer.

Occurs when an invoice was not paid after a grace period.

Occurs when an invoice was paid.

Occurs when an invoice is refunded.

Occurs whenever a project has been created.

Occurs whenever a project has been removed.

The legacy webhook payload is a JSON object with the following keys.

The following event types have been deprecated and webhooks that listen for them can no longer be created. Vercel will continue to deliver the deprecated events to existing webhooks.

Occurs whenever a deployment is created.

Occurs whenever a deployment is ready.

Occurs whenever a deployment is successfully built and your integration has registered at least one check.

Occurs whenever a deployment is canceled.

Occurs whenever a deployment has failed.

Occurs when a user has requested for a check to be rerun after it failed.

Occurs when all checks for a deployment have completed. This does not indicate that they have all passed, only that they are no longer running. It is possible for webhook to occur multiple times for a single deployment if any checks are re-requested.

Each item in checks has the following properties:

Occurs whenever a project has been created.

Occurs whenever a Project has been removed.

Occurs whenever an integration has been removed.

Occurs whenever the user changes the project permission for an integration.

Occurs whenever the user confirms pending scope changes.

Occurs whenever a domain has been created.

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. Therefore, it is recommended 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 request body using your client secret.

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

import crypto from 'crypto';
 
export async function GET(request: Request) {
  const { INTEGRATION_SECRET } = process.env;
 
  if (typeof INTEGRATION_SECRET != 'string') {
    throw new Error('No integration secret found');
  }
 
  const rawBody = await request.text();
  const rawBodyBuffer = Buffer.from(rawBody, 'utf-8');
  const bodySignature = sha1(rawBodyBuffer, INTEGRATION_SECRET);
 
  if (bodySignature !== request.headers.get('x-vercel-signature')) {
    return Response.json({
      code: 'invalid_signature',
      error: "signature didn't match",
    });
  }
 
  const json = JSON.parse(rawBodyBuffer.toString('utf-8'));
 
  switch (json.type) {
    case 'project.created':
    // ...
  }
 
  return new Response('Webhook request validated', {
    status: 200,
  });
}
 
function sha1(data: Buffer, secret: string): string {
  return crypto.createHmac('sha1', secret).update(data).digest('hex');
}

You can compute the signature using an 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.

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.

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 backoff. Events that could not be delivered within 24 hours will not be retried and will be discarded.