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
npx skills add hookdeck/webhook-skills --skill vercel-webhooks -a claude-codeWhat 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.succeededwebhooks - 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-code2Manually: put the files in place
~/.claude/skills/vercel-webhooks/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/vercel-webhooks/
1Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill vercel-webhooks -a codex2Manually: put the files in place
.agents/skills/vercel-webhooks/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill vercel-webhooks -a cursor2Manually: put the files in place
.cursor/skills/vercel-webhooks/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install hookdeck/webhook-skills skills/vercel-webhooks2Manually: put the files in place
.github/skills/vercel-webhooks/SKILL.md1Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill vercel-webhooks -a gemini-cli2Platform CLI
gemini skills install https://github.com/hookdeck/webhook-skills --path skills/vercel-webhooksManually: put the files in place
.devin/skills/vercel-webhooks/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill vercel-webhooks -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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