webflow-webhooks

用途

webflow-webhooks 用于接收和验证 Webflow 平台的 Webhook。当需要搭建 Webflow Webhook 处理器、调试签名验证问题，或处理 Webflow 事件（如表单提交、CMS 集合项变更、电子商务订单）时，可使用本技能。

主要能力

本技能提供一套用于处理 Webflow Webhook 的实现参考，核心是签名验证与事件分发。

签名验证（手动实现）

技能给出 JavaScript 实现，使用 Node.js 的 crypto 模块：

校验时间戳，防止重放攻击，时间窗口为 5 分钟（300000 毫秒）：若当前时间与请求时间戳之差的绝对值超过该窗口，则返回 false。
生成 HMAC 签名：签名内容为 ${timestamp}:${rawBody}，使用 SHA-256 算法，并以十六进制输出。
使用 crypto.timingSafeEqual 进行时间安全比较；若长度不同则捕获异常并返回 false。

代码示例：

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
  }
}

处理事件

技能提供 Express 示例：使用 express.raw({ type: 'application/json' }) 获取原始请求体，从请求头读取 x-webflow-signature 和 x-webflow-timestamp，缺失任一头部则返回 400。随后使用环境变量 WEBFLOW_WEBHOOK_SECRET 进行签名验证，验证失败返回 400。验证通过后解析 JSON，依据 event.triggerType 分发处理，例如 form_submission、ecomm_new_order、collection_item_created 等，最后始终返回 200 以确认接收。

代码示例：

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 项删除	从外部系统移除

环境变量

通过 OAuth 应用创建的 Webhook：WEBFLOW_WEBHOOK_SECRET=your_oauth_client_secret
通过 API 创建（2025 年 4 月之后）的 Webhook：WEBFLOW_WEBHOOK_SECRET=whsec_xxxxx（创建 Webhook 时返回）

本地开发

为进行本地 Webhook 测试，可安装 Hookdeck CLI，然后启动隧道：

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

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

使用方式

按照技能提供的模式：在服务端路由中接收原始请求体；读取签名与时间戳头部；使用对应密钥进行 HMAC 签名验证与时间戳校验；验证通过后解析 payload 并按事件类型分发；最后返回 200 确认接收。

适用场景

设置 Webflow Webhook 处理器
调试签名验证失败问题
处理 form_submission 表单提交事件
处理 Webflow 电子商务订单事件
设置 Webflow CMS 集合项 Webhook

限制与注意事项

通过 Webflow 仪表板创建的 Webhook 不包含签名字段。
只有通过 OAuth 应用或 API 创建的 Webhook 才包含 x-webflow-signature 和 x-webflow-timestamp。
签名验证必须使用原始请求体（raw body），而非解析后的 JSON。
时间戳校验（5 分钟窗口，300000 毫秒）对于防止重放攻击至关重要。
返回 200 状态以确认接收；其他状态会触发重试（最多 3 次）。

技能介绍

用途