vercel-webhooks

Vercel Webhooks

何时使用此技能

• 设置 Vercel webhook 处理程序
• 调试签名验证失败
• 了解 Vercel 事件类型和负载
• 处理部署、项目、域名或集成事件
• 监控部署状态变更

核心代码（请使用）

使用手动验证的 Express Webhook 处理程序

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 处理程序

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}

完整的可运行示例（含测试），请参阅：

• examples/express/ - 完整的 Express 实现
• examples/nextjs/ - Next.js App Router 实现
• examples/fastapi/ - Python FastAPI 实现

常见事件类型

事件	触发时机	常见用例
deployment.created	新部署开始时	开始监控部署、通知团队
deployment.succeeded	部署成功完成时	更新状态、触发部署后任务
deployment.error	部署失败时	提醒团队、执行回滚操作
deployment.canceled	部署取消时	清理资源
project.created	创建新项目时	设置监控、配置资源
project.removed	删除项目时	清理外部资源
domain.created	添加域名时	更新 DNS、SSL 配置

如需完整的事件列表，请参阅 references/overview.md。

环境变量

# Required
VERCEL_WEBHOOK_SECRET=your_webhook_secret_from_dashboard

# Optional (for API calls)
VERCEL_TOKEN=your_vercel_api_token

本地开发

如需在本地测试 webhook，请安装 Hookdeck CLI：

然后启动隧道：

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

无需账号。提供本地隧道和 Web UI，可用于检查请求。

参考资料

• Webhook 概览 - Vercel webhook 的介绍及所有事件类型
• 设置指南 - 在 Vercel 控制面板中配置 webhook
• 签名验证 - SHA1 HMAC 验证详情

推荐：webhook-handler-patterns

如需了解适用于生产环境的 webhook 处理方式，还请安装 webhook-handler-patterns 技能，学习以下内容：

• 处理程序执行顺序 - 正确的操作顺序
• 幂等性 - 处理重复的 webhook
• 错误处理 - 正确的状态码和重试
• 重试逻辑 - 处理暂时性故障

相关技能

• stripe-webhooks - Stripe 支付 webhook
• github-webhooks - GitHub 仓库 webhook
• shopify-webhooks - Shopify 商店 webhook
• sendgrid-webhooks - SendGrid 邮件 webhook
• webhook-handler-patterns - 幂等性、错误处理、重试逻辑
• hookdeck-event-gateway - 可替代队列的 webhook 基础设施，提供有保障的投递、自动重试、重放、速率限制，以及 webhook 处理程序的可观测性