Events

What are the events?

You can subscribe to certain events that are going to be published via Webhooks. An example use-cases for Webhooks might be cleaning up resources after a deploy or any action like that.

Actually the events have not been done mainly for Vercel users, but so that the integrations can do different actions when one of these changes occurs in your projects.

That is why CM Webhook exists, which acts as a proxy between the events received by the integrations and the users of these projects. There are special events that cannot be propagated to users because they are special for when an integration is uninstalled or when its permissions are modified, therefore these events are not exposed to users.

What events can I subscribe to??

The webhook URL receives a HTTP POST request with a JSON payload for each event. On the next Events page, you will be able to see which are the events according to your selection and which is the body that travels through the HTTP request.

What should I reply to the HTTP request?

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

Supported Events

You can find the payload of every event in the Vercel documentation. The supported events are:

  • Deployment events
    • Deployment created: Occurs whenever a deployment is created.
    • Deployment ready: Occurs whenever a deployment is ready. This event get's fired after all blocking checks have passed. See “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 canceled: Occurs whenever a deployment is canceled.
  • Project events
    • Project created: Occurs whenever a project has been created. This event is sent only when CM Webhook has access to all Projects in a Vercel scope.
    • Project removed: Occurs whenever a project has been removed. This event is sent only when CM Webhook has access to all Projects in a Vercel scope.
  • Domain events
    • Domain created: Occurs whenever a domain has been created.
  • Check events
    • 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. Each item in the checks has common properties, check them out in the documentation.
    • Check Rerequested: Occurs when a user has requested for a check to be rerun after it failed.

Unsupported Events

They are not really unsupported events, but they are events that are not of interest to the user (that can change if you as users express it). These are events related to changes in the integration, for example that CM Webhook has been removed from your account or that some permissions have changed. We use them in the following way:

  • Configuration events
    • Configuration removed: Occurs whenever an integration has been removed, in this case, when you as an user removes CM Webhook from your account. In this event we delete all the information associated with your user from our database.
    • Permission updated: Occurs whenever the user changes the permission for an integration, in this case, when you as an user change CM Webhook permissions or scope of these. By changing permissions, some events may not reach our server.
    • Scope changed confirmed: Occurs whenever the user confirms pending scope changes for an integration, in this case, when we, CM Webhook as an integration, change some scope to a higher level, which requires supervision and approval by you as a user.
Webhook URL