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 ハンドラーへの配信保証、自動再試行、再生、レート制限、可観測性を提供します