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
if you registered Checks.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 permission for an Integration.
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.