webflow-webhooks

Webflow Webhooks

フォーム送信、CMS の変更、eコマースの注文、サイトの公開など、Webflow のWebhookイベントを受信、検証、処理します。

クイックスタートワークフロー

前提条件： アクティブなサイトを持つ Webflow アカウントが必要です。署名を検証するには、（ダッシュボードではなく）API 経由でWebhookを作成してください。詳しくはセットアップをご覧ください。

1. Webhookを作成する：希望するイベントタイプのWebhookを Webflow API 経由で登録します
2. イベントを受信する：生のボディを解析する POST リクエストを受け付けるエンドポイントを設定します
3. 署名を検証する：x-webflow-signature ヘッダーと x-webflow-timestamp ヘッダーを検証します
4. イベントを処理する：triggerType によってイベントを振り分け、それぞれに応じた処理を行います
5. 受領を確認する：受信を確認するために 200 を返します（それ以外のステータスでは再試行が行われます）

署名の検証

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');
  }

  const isValid = verifyWebflowSignature(
    req.body.toString(),
    signature,
    timestamp,
    process.env.WEBFLOW_WEBHOOK_SECRET
  );

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

  const event = JSON.parse(req.body);

  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;
    case 'collection_item_published':
      console.log('Published CMS items:', event.payload.items);
      break;
  }

  res.status(200).send('OK');
});

イベントタイプ

Webflow は、フォーム、サイト、ページ、eコマース、CMS、コメントの 6 カテゴリーにわたり、14 種類のWebhookイベントに対応しています。すべてのペイロードスキーマと例を含む完全なリファレンスについては、references/event-types.md をご覧ください。

カテゴリー	イベント	必要なスコープ
フォーム	form_submission	forms:read
サイト	site_publish	sites:read
ページ	page_created, page_metadata_updated, page_deleted	pages:read
eコマース	ecomm_new_order, ecomm_order_changed, ecomm_inventory_changed	ecommerce:read
CMS	collection_item_created, collection_item_changed, collection_item_deleted, collection_item_unpublished, collection_item_published	cms:read
コメント	comment_created	comments:read

環境変数

# 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

ベストプラクティス

1. 必ず署名を検証する：OAuth または API 経由で作成されたWebhookには HMAC-SHA256 検証を使用してください。詳しくは検証をご覧ください
2. 検証には生のボディを使用する：解析済みの JSON に対して検証しないでください。フレームワークを適切に設定してください
3. タイムスタンプを検証する：リプレイ攻撃を防ぐため、5 分の許容範囲（300000ms）を適用します
4. 速やかに 200 を返す：すぐに受信を確認し、負荷の高い処理ではイベントを非同期で処理します
5. 再試行を適切に処理する：Webflow は失敗時に最大 3 回（10 分間隔）再試行します。冪等性を実装してください
6. 本番環境では HTTPS を使用する：セキュリティのため、Webhookエンドポイントでは HTTPS を使用する必要があります

重要な注意事項

• シークレットを平文で扱わないでください。 API トークン、OAuth クライアントシークレット、Webhook署名シークレットは、必ず環境変数またはシークレットマネージャーに保存してください。ユーザーにトークンやシークレットを直接尋ねたり、ソースファイルにハードコードしたりしないでください。
• Webflow のダッシュボードから作成したWebhookには署名ヘッダーが含まれません
• x-webflow-signature と x-webflow-timestamp が含まれるのは、OAuth アプリまたは API 経由で作成したWebhookのみです
• リプレイ攻撃を防ぐには、タイムスタンプの検証（5 分の許容範囲、300000 ミリ秒）が重要です
• 受信を確認するにはステータス 200 を返してください。それ以外のステータスでは再試行が行われます（最大 3 回、10 分間隔）

リファレンスドキュメント

各リファレンスファイルには、検索しやすいように name、description、tags を含む YAML フロントマターがあります。タグやキーワードから関連するリファレンスをすばやく見つけるには、scripts/search_references.py にある検索スクリプトを使用してください。

• references/event-types.md：14 種類すべてのイベントタイプについて、スコープ、ペイロードスキーマ、例をまとめた完全なリファレンス
• references/webhook-api.md：Webhook の作成、一覧表示、取得、削除を行う REST API v2 エンドポイント
• references/overview.md：Webhook の概念、配信動作、制限、セキュリティ上の考慮事項
• references/setup.md：ダッシュボードと API の設定、OAuth、スコープ、環境設定
• references/verification.md：HMAC-SHA256 署名検証、よくある注意点、デバッグ
• references/faq.md：配信の問題、署名の検証失敗、API エラーに関する FAQ とトラブルシューティング

リファレンスの検索

# List all references with metadata
python scripts/search_references.py --list

# Search by tag (exact match)
python scripts/search_references.py --tag <tag>

# Search by keyword (across name, description, tags, and content)
python scripts/search_references.py --search <query>

スクリプト

• scripts/search_references.py：タグやキーワードでリファレンスファイルを検索したり、メタデータ付きですべて一覧表示したりします