webflow-webhooks

Webflow Webhooks

何时使用此技能

• 如何接收 Webflow Webhooks？
• 如何验证 Webflow Webhook 签名？
• 如何处理来自 Webflow 的 form_submission 事件？
• 如何处理 Webflow 电商订单事件？
• 为什么我的 Webflow Webhook 签名验证失败？
• 设置 Webflow CMS 集合项 Webhooks

核心代码

手动验证签名

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	新电商订单创建时	订单处理、库存管理
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 枚举包含这些类型以及 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 界面，用于检查请求。

资源

• 什么是 Webflow Webhooks - 事件类型和负载结构
• 设置 Webflow Webhooks - 控制面板配置和 API 设置
• 签名验证详情 - 深入了解验证指南
• Express 示例 - 带测试的 Node.js 实现
• Next.js 示例 - App Router 实现
• FastAPI 示例 - Python 实现

重要说明

• 通过 Webflow 控制面板创建的 Webhooks 不包含签名标头
• 只有通过 OAuth 应用或 API 创建的 Webhooks 才包含 x-webflow-signature 和 x-webflow-timestamp
• 验证签名时务必使用原始请求体，而不是解析后的 JSON
• 时间戳验证（5 分钟窗口，即 300000 毫秒）对于防止重放攻击至关重要
• 返回 200 状态码以确认收到；其他状态码会触发重试（最多 3 次）

推荐：webhook-handler-patterns

此技能与 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 签名更新日志