webflow-webhooks

Webflow Webhooks

このスキルを使用する場面

• Webflow の Webhook を受信するにはどうすればよいですか？
• Webflow の Webhook 署名を検証するにはどうすればよいですか？
• Webflow の form_submission イベントを処理するにはどうすればよいですか？
• Webflow の eコマース注文イベントを処理するにはどうすればよいですか？
• Webflow の Webhook 署名検証に失敗するのはなぜですか？
• Webflow CMS コレクションアイテムの Webhook を設定する

必須コード

署名検証（手動）

const crypto = require('crypto');

function verifyWebflowSignature(rawBody, signature, timestamp, secret) {
  // Check timestamp to prevent replay attacks (5 minute window - 300000 milliseconds)
  const currentTime = Date.now();
  if (Math.abs(currentTime - parseInt(timestamp)) > 300000) {
    return false;
  }

  // Generate HMAC signature
  const signedContent = `${timestamp}:${rawBody}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedContent)
    .digest('hex');

  // Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    );
  } catch {
    return false; // Different lengths = invalid
  }
}

イベントの処理

app.post('/webhooks/webflow', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webflow-signature'];
  const timestamp = req.headers['x-webflow-timestamp'];

  if (!signature || !timestamp) {
    return res.status(400).send('Missing required headers');
  }

  // Verify signature (use OAuth client secret or webhook-specific secret)
  const isValid = verifyWebflowSignature(
    req.body.toString(),
    signature,
    timestamp,
    process.env.WEBFLOW_WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(400).send('Invalid signature');
  }

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

  // Handle different event types
  switch (event.triggerType) {
    case 'form_submission':
      console.log('New form submission:', event.payload.data);
      break;
    case 'ecomm_new_order':
      console.log('New order:', event.payload);
      break;
    case 'collection_item_created':
      console.log('New CMS item:', event.payload);
      break;
    // Add more event handlers as needed
  }

  // Always return 200 to acknowledge receipt
  res.status(200).send('OK');
});

一般的なイベントタイプ

イベント	発生条件	使用例
form_submission	サイトでフォームが送信されたとき	問い合わせフォーム、リードの獲得
site_publish	サイトが公開されたとき	キャッシュのクリア、ビルドの開始
ecomm_new_order	新しい eコマース注文があったとき	注文処理、在庫管理
ecomm_order_changed	注文ステータスが変更されたとき	フルフィルメントシステムの更新
collection_item_created	CMS アイテムが作成されたとき	コンテンツのシンジケーション
collection_item_changed	CMS アイテムが更新されたとき	外部システムの更新
collection_item_deleted	CMS アイテムが削除されたとき	外部システムからの削除
collection_item_published	CMS アイテムが公開されたとき	キャッシュの無効化、後続システムへの公開

Webflow は All Events に 13 種類のイベントを記載しています。公式の webflow-api SDK の TriggerType enum には、それらに加えて collection_item_published が含まれています。user_account_* イベントは非推奨です。詳しくは references/overview.md をご覧ください。

環境変数

# For webhooks created via OAuth App
WEBFLOW_WEBHOOK_SECRET=your_oauth_client_secret

# For webhooks created via API (after April 2025)
WEBFLOW_WEBHOOK_SECRET=whsec_xxxxx  # Returned when creating webhook

ローカル開発

ローカルで Webhook をテストするには、Hookdeck CLI をインストールします。

次に、トンネルを起動します。

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

アカウントは不要です。ローカルトンネルと、リクエストを確認するための Web UI が利用できます。

リソース

• Webflow Webhook とは - イベントタイプとペイロードの構造
• Webflow Webhook の設定 - ダッシュボードの設定と API の設定
• 署名検証の詳細 - 詳細な検証ガイド
• Express の例 - テスト付きの Node.js 実装
• Next.js の例 - App Router の実装
• FastAPI の例 - Python の実装

重要な注意事項

• Webflow ダッシュボードから作成した Webhook には、署名ヘッダーが含まれません
• OAuth アプリまたは API 経由で作成した Webhook のみ、x-webflow-signature と x-webflow-timestamp が含まれます
• 署名検証には、解析済みの JSON ではなく、必ず生のボディを使用してください
• リプレイ攻撃を防ぐには、タイムスタンプの検証（5 分間、つまり 300000 ミリ秒）が重要です
• 受信を確認するために 200 ステータスを返してください。それ以外のステータスでは再試行されます（最大 3 回）

推奨：webhook-handler-patterns

本スキルは、production-ready な実装に向けて webhook-handler-patterns と併用できます。

• ハンドラーの順序 — リクエストのフローとミドルウェアの順序
• 冪等性 — 重複イベントの処理
• エラー処理 — 適切な障害処理と復旧
• 再試行ロジック — 処理に失敗した場合の対応

関連スキル

• stripe-webhooks - 同様の HMAC-SHA256 検証を用いた Stripe webhook の処理
• shopify-webhooks - Shopify webhook の実装
• github-webhooks - GitHub webhook の処理
• webhook-handler-patterns - あらゆる webhook に対応する本番環境向けパターン
• hookdeck-event-gateway - Webhook のインフラストラクチャと信頼性

出典：

• Webhook の利用 – Webflow ドキュメント
• Webhook 署名の変更履歴