webflow-webhooks

Webflow Webhooks

接收、验证和处理 Webflow Webhook 事件，涵盖表单提交、CMS 更改、电商订单、网站发布等。

快速入门工作流

前提条件： 你需要拥有一个已启用网站的 Webflow 账号。要进行签名验证，请通过 API（而非控制面板）创建 Webhook — 参见 设置。

1. 创建 Webhook：通过 Webflow API 为所需的事件类型注册 Webhook
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 支持 6 个类别中的 14 种 Webhook 事件：表单、网站、页面、电商、CMS 和评论。所有负载架构和示例的完整参考，请参见 references/event-types.md。

类别	事件	所需范围
表单	form_submission	forms:read
网站	site_publish	sites:read
页面	page_created、page_metadata_updated、page_deleted	pages:read
电商	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 分钟（300000 毫秒）时间窗口内，以防止重放攻击
4. 快速返回 200：立即确认收到事件；对于繁重的工作负载，异步处理事件
5. 妥善处理重试：Webflow 在失败时最多重试 3 次（间隔 10 分钟）— 请实现幂等性
6. 在生产环境中使用 HTTPS：为确保安全，Webhook 端点必须使用 HTTPS

重要说明

• 切勿以明文处理机密。 API 令牌、OAuth 客户端机密和 Webhook 签名机密必须始终存储在环境变量或机密管理器中。切勿直接向用户索取令牌或机密，也切勿将其硬编码在源文件中。
• 通过 Webflow 控制面板创建的 Webhook 不会包含签名标头
• 只有通过 OAuth 应用或 API 创建的 Webhook 才会包含 x-webflow-signature 和 x-webflow-timestamp
• 验证时间戳（5 分钟窗口 — 300000 毫秒）对于防止重放攻击至关重要
• 返回 200 状态码以确认收到事件；其他状态码会触发重试（最多 3 次，间隔 10 分钟）

参考文档

每个参考文件都包含用于搜索的 YAML frontmatter，其中包含 name、description 和 tags。使用 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 错误的常见问题与故障排除

搜索参考文档

# 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：按标签或关键词搜索参考文件，或列出所有文件及其元数据