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 when an integration deployment action or the deployment itself is canceled.

Occurs when a deployment that executed an integration deployment action is cleaned up, such as due to the deployment retention policy.

Occurs when a deployment starts an integration deployment action.

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 a domain's auto-renewal setting is changed.

Occurs whenever a new SSL certificate is added for a domain.

Occurs whenever adding a new SSL certificate for a domain fails.

Occurs whenever an SSL certificate is deleted for a domain.

Occurs whenever an SSL certificate is renewed for a domain.

Occurs whenever renewing an SSL certificate for a domain fails.

Occurs whenever DNS records for a domain are modified.

Occurs whenever a domain is renewed.

Occurs whenever a domain renewal fails.

Occurs whenever a domain transfer into Vercel is completed.

Occurs whenever a domain transfer into Vercel fails.

Occurs whenever a domain transfer into Vercel is initiated.

Occurs whenever a domain is added to a project.

Occurs whenever a domain is removed from a project.

Occurs whenever a domain is moved from one project to another.

Occurs whenever a project domain becomes unverified.

Occurs whenever a project domain is updated.

Occurs whenever a project domain is verified.

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 whenever the user connects the integration resource to a project.

Occurs whenever the user disconnects the integration resource to a project.

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.

Occurs whenever a rolling release stage is approved and progresses to the next stage.

Occurs whenever a rolling release is completed successfully.

Occurs whenever a rolling release is aborted.

Occurs whenever a rolling release is started.

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.