Vercel sends webhook events during deployments so you can track what happened and build your own automation.
A couple of important notes up front:
- Webhook delivery order is not guaranteed. You may receive events out of order.
- Each event includes timestamps you can use to sort events on your side.
Use these fields to correlate and store state:
message.type
message.createdAt
message.payload.user.id
message.payload.team.id
message.payload.project.id
// correlates events for a single deployment
message.payload.deployment.id deployment.createddeployment.succeededdeployment.promoted(unless the current production environment is in a rollback state)
deployment.rollback(payload includesfromDeploymentIdandtoDeploymentId)- There is no event emitted when the rollback completes
deployment.createddeployment.succeeded
deployment.promoted
deployment.error
If you want to model deployment state in your webhook receiver, a simple approach is:
- Track a per-deployment lifecycle:
created → succeeded → promoted - Track a per-project production mode:
normal ↔ rollback
When you receive deployment.succeeded, you can also check whether the project is currently in rollback mode. If it is, you can log something like:
- “Deployment succeeded, but production is currently serving a rollback target.”
This makes it easier to understand why a deployment succeeded while production is intentionally pinned to an earlier deployment.
- Webhook events have no guaranteed delivery order. Receivers should use timestamps in the payload to order events.
- There is no event when a rollback completes.
deployment.promoteddoes not include a unique field that differentiates a manual promotion from one that occurred as part of a standard commit-driven flow.
Here is some example code that can used as a reference for how to build your own webhook receiver to track the state.
