Webhooks

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

Supported Event Types

When you configure a webhook URL from your Integrations Settings page, it receives an HTTP POST request with a JSON payload for each event.

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

deployment

Occurs whenever a Deployment is created.

deployment-ready

Occurs whenever a Deployment is ready.

deployment-prepared

Occurs whenever a Deployment is successfully built and your integration has registered at least one Check.

deployment-error

Occurs whenever a Deployment has failed.

deployment-check-rerequested

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

deployment-checks-completed

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

project-created

Occurs whenever a Project has been created.

project-removed

Occurs whenever a Project has been removed.

integration-configuration-removed

Occurs whenever an Integration has been removed.

integration-configuration-permission-updated

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

integration-configuration-scope-change-confirmed

Occurs whenever the user confirms pending scope changes.

domain-created

Occurs whenever a Domain has been created.

Securing webhooks

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 payload body using your client secret.

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

const crypto = require('crypto');
const { send } = require('micro');

module.exports = (req, res) => {
  const payload = await json(req);

  if (!verifySignature(req, payload)) {
    return send(res, 403, {
      code: `invalid_signature`,
      error: `signature didn't match`,
    });
  }

  // Process the payload
};

function verifySignature(req, payload) {
  const signature = crypto
    .createHmac('sha1', process.env.OAUTH2_SECRET)
    .update(payload)
    .digest('hex');
  return signature === req.headers['x-vercel-signature'];
}

Example on how to validate a webhook message.

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.

HTTP Response

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.

Delivery Attempts and Retries

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.