Deployment Webhooks

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.

How to correlate events

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 

Events

Events triggered by commit

• deployment.created
• deployment.succeeded
• deployment.promoted (unless the current production environment is in a rollback state)

Events triggered when initiating an Instant Rollback

• deployment.rollback (payload includes fromDeploymentId and toDeploymentId)
• There is no event emitted when the rollback completes

Events triggered while in rollback state

• deployment.created
• deployment.succeeded

Events triggered when promoting a deployment to production

• deployment.promoted

Events triggered on deployment errors

• deployment.error

Recommended receiver behavior (simple state machine)

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.

Known limitations

• 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.promoted does not include a unique field that differentiates a manual promotion from one that occurred as part of a standard commit-driven flow.

Demo

Here is some example code that can used as a reference for how to build your own webhook receiver to track the state.

apps/webhook/api/webhook.js