vercel-webhooks — скилл для Claude Code: обработка вебхуков Vercel
Скилл vercel-webhooks для приёма и проверки вебхуков Vercel прямо в коде. Помогает при настройке обработчиков, отладке проверки подписей и реагировании на события развёртывания и проектов.
MIT 204 установок ★ 103 обновлён 2026-10-22
npx skills add hookdeck/webhook-skills --skill vercel-webhooks -a claude-codeЧто делает vercel-webhooks
Скилл поставляет готовые примеры на JavaScript (Express), Python (FastAPI) и Next.js для обработки вебхуков Vercel. Центр — правильная проверка подписей через SHA1 HMAC с использованием x-vercel-signature заголовка. Код показывает, как парсить события вроде deployment.created, deployment.succeeded, deployment.error и project.created, а также как выбрать правильный способ чтения сырого тела запроса (для Express это express.raw(), важно не забыть).
Для локальной разработки скилл советует использовать Hookdeck CLI туннель (npx hookdeck-cli listen 3000 vercel), чтобы перенаправлять вебхуки на локальный сервер без публикации. В сырых примерах есть таблица основных типов событий и ссылки на справку по полной схеме — обзор вебхуков, настройка в дашборде Vercel, детали проверки подписей.
Скилл требует переменной окружения VERCEL_WEBHOOK_SECRET из дашборда Vercel — без неё проверка подписей не сработает. Рекомендуется установить дополнительный скилл webhook-handler-patterns для обработки дублей, ошибок и повторных попыток в боевом коде.
Какие задачи решает
- настроить обработчик вебхуков Vercel на своём сервере
- проверить подпись вебхука и убедиться в его подлинности
- реагировать на события развёртывания и создания проектов
- отладить отказ проверки подписи
- протестировать вебхуки локально без публикации
Примеры запросов агенту
- Покажи, как сделать Express-сервер для приёма вебхуков
deployment.succeededот Vercel - Как проверить подпись вебхука Vercel с помощью SHA1 HMAC?
- Сделай обработчик FastAPI для событий Vercel и объясни, какой заголовок содержит подпись
Как установить vercel-webhooks
1Через Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill vercel-webhooks -a claude-code2Вручную: положить файлы
~/.claude/skills/vercel-webhooks/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/vercel-webhooks/
1Через Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill vercel-webhooks -a codex2Вручную: положить файлы
.agents/skills/vercel-webhooks/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill vercel-webhooks -a cursor2Вручную: положить файлы
.cursor/skills/vercel-webhooks/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install hookdeck/webhook-skills skills/vercel-webhooks2Вручную: положить файлы
.github/skills/vercel-webhooks/SKILL.md1Через Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill vercel-webhooks -a gemini-cli2Командой платформы
gemini skills install https://github.com/hookdeck/webhook-skills --path skills/vercel-webhooksВручную: положить файлы
.devin/skills/vercel-webhooks/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill vercel-webhooks -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о vercel-webhooks
Как установить vercel-webhooks в Claude Code?
Выполни npx skills add hookdeck/webhook-skills --skill vercel-webhooks -a claude-code, затем открой ~/.claude/skills/vercel-webhooks/SKILL.md для справки по использованию.
Что делает vercel-webhooks?
Скилл содержит примеры кода для приёма вебхуков от Vercel, проверки их подлинности через HMAC-подпись и обработки событий вроде развёртывания или создания проекта.
Какую переменную окружения нужно установить для работы?
Требуется VERCEL_WEBHOOK_SECRET из дашборда Vercel — она используется для проверки HMAC-подписей входящих вебхуков.
Исходный текст
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