How to Test Vercel Webhooks Locally

What Webhooks Does Vercel Send?

Vercel sends webhooks for deployment lifecycle events through its integration platform. The primary events are deployment.created (new deployment started), deployment.succeeded (deployment completed successfully), deployment.ready (deployment is live), deployment.error (deployment failed), and deployment.canceled. Additionally, there are project.created, project.removed, and domain-related events.

Each webhook payload includes the event type, a payload object with deployment details (project name, URL, git branch, commit SHA, creator, and build metadata), and a timestamp. For deployment events, the payload includes the deployment URL, state, build logs URL, and the git metadata that triggered the deployment.

Vercel uses HMAC-SHA1 signatures for webhook verification. The x-vercel-signature header contains the signature computed using your integration's client secret and the raw request body. Note that Vercel uses SHA1 (not SHA256) for its webhook signatures.

Setting Up Vercel Webhooks

There are two ways to receive Vercel webhooks: through the Integrations platform or through project-level webhook configurations. For project-level webhooks, go to your project's Settings > Git > Deploy Hooks section, or use the Vercel REST API.

For integration-level webhooks, create a Vercel Integration at vercel.com/integrations. Configure your ReqPour URL as the webhook endpoint. This gives you events across all projects the integration is installed on.

For simpler project-specific monitoring, use the Vercel API:

curl -X POST "https://api.vercel.com/v1/webhooks" \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://abc123.reqpour.com/vercel",
    "events": ["deployment.created", "deployment.succeeded", "deployment.error"]
  }'

Start the ReqPour relay and trigger a deployment by pushing to your repository. Watch the event sequence: deployment.created, then deployment.succeeded (or deployment.error), then deployment.ready.

Handling Vercel Deployment Events

Here is a handler that processes Vercel deployment webhooks:

const crypto = require('crypto');

app.post('/vercel', express.json(), (req, res) => { const signature = req.headers['x-vercel-signature']; const body = JSON.stringify(req.body); const expected = crypto .createHmac('sha1', process.env.VERCEL_CLIENT_SECRET) .update(body) .digest('hex');

if (signature !== expected) { return res.status(401).send('Invalid signature'); }

const { type, payload } = req.body;

switch (type) { case 'deployment.created': console.log(Deployment started: ${payload.deployment.url}); notifySlack(Deploying ${payload.name} from ${payload.deployment.meta?.githubCommitRef}); break; case 'deployment.succeeded': console.log(Deployment succeeded: ${payload.deployment.url}); notifySlack(Deployed successfully: https://${payload.deployment.url}); break; case 'deployment.error': console.log(Deployment failed: ${payload.deployment.url}); notifySlack(Deployment failed for ${payload.name}); break; }

res.status(200).send('OK'); }); ```

Common use cases include posting deployment notifications to Slack or Discord, updating a status page, triggering post-deployment tests, or logging deployment history to your own analytics system.

Building Deployment Pipelines

Vercel webhooks are the foundation for building custom deployment pipelines. For example, when a deployment succeeds, you might want to run smoke tests against the preview URL, update a deployment log in your database, or notify stakeholders in Slack.

With ReqPour, you can capture deployment event payloads and examine them to understand what data is available. The deployment payload includes the git commit SHA, branch name, commit message, and author — useful for creating rich deployment notifications.

For staging-to-production workflows, listen for deployment.succeeded on preview deployments, run automated tests against the preview URL, and if they pass, promote to production using the Vercel API. ReqPour's request history lets you review the complete deployment event timeline, including any build errors or delays.

Vercel Webhook Tips

Vercel sends events for all deployments, including automatic deployments triggered by git pushes and manual deployments. Use the payload.deployment.meta field to distinguish between sources and filter events your handler cares about.

The deployment.ready event fires when the deployment URL is actually accessible, which may be slightly after deployment.succeeded. If your post-deployment logic needs to access the deployed site (like running smoke tests), wait for deployment.ready rather than deployment.succeeded.

During development, use ReqPour to test your deployment notification flow without making actual deployments. Capture a deployment.succeeded event once, then replay it while iterating on your notification format, Slack message templates, or database logging logic. This saves time compared to pushing dummy commits to trigger real deployments.