Skip to main content
skill CX Codex

vercel-webhooks — Claude Code skill: receive Vercel webhooks

Skill for receiving and verifying Vercel webhooks directly in code. Handles webhook setup, signature verification debugging, and reacting to deployment and project events.

MIT 204 installs ★ 103 updated 2026-10-22

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add hookdeck/webhook-skills --skill vercel-webhooks -a claude-code
Open on GitHub

What vercel-webhooks does

The skill includes ready-to-use examples in JavaScript (Express), Python (FastAPI), and Next.js for processing Vercel webhooks. The core pattern is verifying signatures using SHA1 HMAC with the x-vercel-signature header. Code samples show how to parse events such as deployment.created, deployment.succeeded, deployment.error, and project.created, plus handling raw request bodies correctly (Express requires express.raw()).

For local development, the skill recommends the Hookdeck CLI tunnel (npx hookdeck-cli listen 3000 vercel) to route webhooks to your local server without public deployment. Examples include a table of common event types and links to reference material—webhook overview, Vercel dashboard setup, and signature verification details.

The skill requires the VERCEL_WEBHOOK_SECRET environment variable from your Vercel dashboard; without it, signature verification fails. Pairing with the webhook-handler-patterns skill helps handle duplicate webhooks, errors, and retries in production.

What it helps with

  • set up a Vercel webhook receiver on your server
  • verify webhook signatures and confirm authenticity
  • react to deployment and project creation events
  • debug signature verification failures
  • test webhooks locally without publishing

Example prompts for the agent

  • Show me an Express server for receiving Vercel deployment.succeeded webhooks
  • How do I verify a Vercel webhook signature using SHA1 HMAC?
  • Build a FastAPI handler for Vercel events and explain which header carries the signature

How to install vercel-webhooks

1Skills CLI (Vercel)

npx skills add hookdeck/webhook-skills --skill vercel-webhooks -a claude-code

2Manually: put the files in place

~/.claude/skills/vercel-webhooks/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/vercel-webhooks/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about vercel-webhooks

How do I install vercel-webhooks in Claude Code?

Run npx skills add hookdeck/webhook-skills --skill vercel-webhooks -a claude-code, then open ~/.claude/skills/vercel-webhooks/SKILL.md for usage details.

What does vercel-webhooks do?

The skill provides code examples for receiving webhooks from Vercel, verifying their authenticity via HMAC signature, and handling events such as deployments or project creation.

What environment variable is required?

You need VERCEL_WEBHOOK_SECRET from the Vercel dashboard—it's used to verify HMAC signatures on incoming webhooks.

Source text

SKILL.md · MIT
---
name: vercel-webhooks
description: >
  Receive and verify Vercel webhooks. Use when setting up Vercel webhook
  handlers, debugging signature verification, or handling deployment events
  like deployment.created, deployment.succeeded, or project.created.
license: MIT
metadata:
  author: hookdeck
  version: "0.1.0"
  repository: https://github.com/hookdeck/webhook-skills
---

# Vercel Webhooks

## When to Use This Skill

- Setting up Vercel webhook handlers
- Debugging signature verification failures
- Understanding Vercel event types and payloads
- Handling deployment, project, domain, or integration events
- Monitoring deployment status changes

## Essential Code (USE THIS)

### Express Webhook Handler with Manual Verification

```javascript
const express = require('express');
const crypto = require('crypto');

const app = express();

// CRITICAL: Use express.raw() for webhook endpoint - Vercel needs raw body
app.post('/webhooks/vercel',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.headers['x-vercel-signature'];

    if (!signature) {
      return res.status(400).send('Missing x-vercel-signature header');
    }

    // Verify signature using SHA1 HMAC
    const expectedSignature = crypto
      .createHmac('sha1', process.env.VERCEL_WEBHOOK_SECRET)
      .update(req.body)
      .digest('hex');

    // Use timing-safe comparison
    let signaturesMatch;
    try {
      signaturesMatch = crypto.timingSafeEqual(
        Buffer.from(signature),
        Buffer.from(expectedSignature)
      );
    } catch (err) {
      // Buffer length mismatch = invalid signature
      signaturesMatch = false;
    }

    if (!signaturesMatch) {
      console.error('Invalid Vercel webhook signature');
      return res.status(400).send('Invalid signature');
    }

    // Parse the verified payload
    const event = JSON.parse(req.body.toString());

    // Handle the event
    switch (event.type) {
      case 'deployment.created':
        console.log('Deployment created:', event.payload.deployment.id);
        break;
      case 'deployment.succeeded':
        console.log('Deployment succeeded:', event.payload.deployment.id);
        break;
      case 'deployment.error':
        console.log('Deployment failed:', event.payload.deployment.id);
        break;
      case 'project.created':
        console.log('Project created:', event.payload.project.name);
        break;
      default:
        console.log('Unhandled event:', event.type);
    }

    res.json({ received: true });
  }
);
```

### Python (FastAPI) Webhook Handler

```python
import os
import hmac
import hashlib
from fastapi import FastAPI, Request, HTTPException, Header

app = FastAPI()
webhook_secret = os.environ.get("VERCEL_WEBHOOK_SECRET")

@app.post("/webhooks/vercel")
async def vercel_webhook(
    request: Request,
    x_vercel_signature: str = Header(None)
):
    if not x_vercel_signature:
        raise HTTPException(status_code=400, detail="Missing x-vercel-signature header")

    # Get raw body
    body = await request.body()

    # Compute expected signature
    expected_signature = hmac.new(
        webhook_secret.encode(),
        body,
        hashlib.sha1
    ).hexdigest()

    # Timing-safe comparison
    if not hmac.compare_digest(x_vercel_signature, expected_signature):
        raise HTTPException(status_code=400, detail="Invalid signature")

    # Parse verified payload
    event = await request.json()

    # Handle event
    if event["type"] == "deployment.created":
        print(f"Deployment created: {event['payload']['deployment']['id']}")
    elif event["type"] == "deployment.succeeded":
        print(f"Deployment succeeded: {event['payload']['deployment']['id']}")
    # ... handle other events

    return {"received": True}
```

> **For complete working examples with tests**, see:
> - [examples/express/](examples/express/) - Full Express implementation
> - [examples/nextjs/](examples/nextjs/) - Next.js App Router implementation
> - [examples/fastapi/](examples/fastapi/) - Python FastAPI implementation

## Common Event Types

| Event | Triggered When | Common Use Cases |
|-------|----------------|------------------|
| `deployment.created` | A new deployment starts | Start deployment monitoring, notify team |
| `deployment.succeeded` | Deployment completes successfully | Update status, trigger post-deploy tasks |
| `deployment.error` | Deployment fails | Alert team, rollback actions |
| `deployment.canceled` | Deployment is canceled | Clean up resources |
| `project.created` | New project is created | Set up monitoring, configure resources |
| `project.removed` | Project is deleted | Clean up external resources |
| `domain.created` | Domain is added | Update DNS, SSL configuration |

See [references/overview.md](references/overview.md) for the complete event list.

## Environment Variables

```bash
# Required
VERCEL_WEBHOOK_SECRET=your_webhook_secret_from_dashboard

# Optional (for API calls)
VERCEL_TOKEN=your_vercel_api_token
```

## Local Development

For local webhook testing, install Hookdeck CLI:

```bash
```

Then start the tunnel:

```bash
npx hookdeck-cli listen 3000 vercel --path /webhooks/vercel
```

No account required. Provides local tunnel + web UI for inspecting requests.

## Reference Materials

- [Webhook Overview](references/overview.md) - What Vercel webhooks are, all event types
- [Setup Guide](references/setup.md) - Configure webhooks in Vercel dashboard
- [Signature Verification](references/verification.md) - SHA1 HMAC verification details

## Recommended: webhook-handler-patterns

For production-ready webhook handling, also install the `webhook-handler-patterns` skill to learn:

- [Handler sequence](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/handler-sequence.md) - Correct order of operations
- [Idempotency](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/idempotency.md) - Handle duplicate webhooks
- [Error handling](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/error-handling.md) - Proper status codes and retries
- [Retry logic](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/retry-logic.md) - Handle transient failures

## Related Skills

- [stripe-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/stripe-webhooks) - Stripe payment webhooks
- [github-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/github-webhooks) - GitHub repository webhooks
- [shopify-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/shopify-webhooks) - Shopify store webhooks
- [sendgrid-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/sendgrid-webhooks) - SendGrid email webhooks
- [webhook-handler-patterns](https://github.com/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns) - Idempotency, error handling, retry logic
- [hookdeck-event-gateway](https://github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway) - Webhook infrastructure that replaces your queue — guaranteed delivery, automatic retries, replay, rate limiting, and observability for your webhook handlers

© hookdeck · MIT · hookdeck/webhook-skills

Similar skills

All skills for Backend and APIs →

From the same set39

The whole set →
elevenlabs-webhooks Teaches your coding assistant how to verify and handle ElevenLabs webhooks. Useful when implementing call transcript handlers or debugging signature validation. CX Codex +1 237installs hookdeck-event-gateway Connects Hookdeck Event Gateway — webhook infrastructure with queue, retries and monitoring. CX Codex +1 214installs woocommerce-webhooks Sets up and validates WooCommerce webhooks in Node.js and Python. Handles signature verification and store events like order or product updates. CX Codex +1 213installs clerk-webhooks This skill guides you through receiving Clerk webhooks and checking their signatures. Use it when building handlers for user, session, or organization events. CX Codex +1 210installs postmark-webhooks Configures handlers for Postmark webhooks. It processes bounces, opens, clicks, spam complaints, and inbound messages. CX Codex +1 203installs openai-webhooks A skill for receiving and verifying OpenAI webhooks. Use it to process fine-tuning events, batch completions, and realtime API callbacks with built-in signature validation. CX Codex +1 202installs cursor-webhooks Set up a handler for Cursor Cloud Agent webhooks, verify request signatures, and respond to agent status changes. Useful when wiring webhook events into an app. CX Codex +1 200installs deepgram-webhooks A skill for receiving and verifying Deepgram webhooks. Use when you need to handle asynchronous transcription results or build a callback handler for completed transcription requests. CX Codex +1 200installs

Project sponsors

Companies that keep this analytics open