Webhook 集成指南 | GroMach

概述

Webhook 集成允许您从 GroMach 接收文章数据并在您自己的后端系统中进行处理。当您发布文章时，GroMach 会向您配置的端点发送包含文章内容的 POST 请求。

步骤 1：设置 Webhook 端点

在您的服务器上创建一个 HTTPS 端点来接收 webhook 请求。该端点必须满足以下要求：

接受 POST 请求：所有 webhook 数据都通过 POST 方式发送
使用 HTTPS：出于安全考虑，仅支持 HTTPS URL
返回 2xx 状态码：返回成功状态码以确认接收

步骤 2：实现签名验证

GroMach 使用 HMAC-SHA256 对所有 webhook 请求进行签名。您应该验证此签名以确保请求的真实性。

每个请求都包含以下请求头：

x-webhook-signature：请求体的 HMAC-SHA256 签名
x-webhook-timestamp：请求发送时的 ISO 8601 时间戳
Content-Type：application/json

以下是 Node.js 中签名验证的示例：

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(computedSignature, 'hex')
  );
}

// 在您的端点处理程序中：
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifySignature(payload, signature, YOUR_SECRET_KEY)) {
    return res.status(401).json({ error: '签名无效' });
  }

  // 处理 webhook...
  res.json({ success: true });
});

步骤 3：Webhook 数据格式

当文章发布时，GroMach 会发送以下结构的数据：

{
  "event_type": "publish_articles",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "articles": [
      {
        "id": "article-uuid-123",
        "slug": "my-article-slug",
        "title": "文章标题",
        "excerpt": "文章的简要描述...",
        "content_format": "markdown",
        "content": "# Markdown 格式的完整文章内容...",
        "status": "published",
        "published_at": "2024-01-15T10:30:00.000Z",
        "author_name": "Admin",
        "cover_image": "https://example.com/image.jpg",
        "meta_title": "SEO 标题",
        "meta_description": "SEO 元描述",
        "tags": ["seo", "marketing"]
      }
    ]
  }
}

文章字段说明

id：文章的唯一标识符
slug：用于 URL 的文章标识符
title：文章标题
excerpt：简要描述或摘要
content_format："markdown" 或 "html"
content：完整的文章内容
status：发布状态（draft、published、archived）
published_at：ISO 8601 格式的发布时间
author_name：作者显示名称
cover_image：封面图片 URL（如果有）
meta_title：搜索引擎优化标题
meta_description：SEO 元描述
tags：标签字符串数组

步骤 4：在 GroMach 中配置

在 GroMach 集成页面中，填写以下信息：

名称（可选）：用于标识此 webhook 的友好名称
Webhook URL：您的 HTTPS 端点 URL（例如 https://your-site.com/api/webhook）
密钥：用于签名请求的密钥字符串（请妥善保管！）
发布状态：选择文章是以「已发布」还是「草稿」状态发送

重要提示

请妥善保管您的密钥，切勿在客户端代码中暴露。建议使用环境变量在服务器上安全存储。

测试 Webhook

在创建集成之前，您可以使用「测试连接」按钮来验证您的 webhook 端点是否正确配置。 GroMach 会发送一个测试请求来验证连接。

测试要求

要通过测试，您的端点必须：

1. 验证签名：使用密钥验证 X-Webhook-Signature 请求头
2. 返回成功响应：返回包含 { "success": true } 的 JSON 响应

测试数据格式如下：

{
  "event_type": "test",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "message": "This is a test webhook from Gromach SEO",
    "integration_name": "My Webhook"
  }
}

以下是您的测试端点应如何处理请求的完整示例：

const crypto = require('crypto');

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);

  // 步骤 1：验证签名
  const computedSignature = crypto
    .createHmac('sha256', YOUR_SECRET_KEY)
    .update(payload)
    .digest('hex');

  const isValid = crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(computedSignature, 'hex')
  );

  if (!isValid) {
    return res.status(401).json({
      success: false,
      error: '签名无效'
    });
  }

  // 步骤 2：根据事件类型处理
  if (req.body.event_type === 'test') {
    // 测试连接 - 直接返回成功
    return res.json({ success: true });
  }

  if (req.body.event_type === 'publish_articles') {
    // 处理文章...
    const articles = req.body.data.articles;
    // 保存到数据库等操作
    return res.json({ success: true });
  }

  res.json({ success: true });
});

为什么需要签名验证

签名验证确保 webhook 请求确实来自 GroMach 且未被篡改。这是一种安全最佳实践，可以保护您的端点免受未授权请求的攻击。

故障排除

连接测试失败

• 确认您的端点 URL 正确且使用 HTTPS
• 确保您的服务器可以从互联网访问
• 检查您的端点是否返回 2xx 状态码

签名验证失败

• 确保您使用的是 GroMach 中完全相同的密钥
• 确认您正在对原始请求体进行哈希，而不是解析后的对象
• 使用时间安全比较以防止计时攻击

文章未显示

• 检查服务器日志中是否有处理错误
• 验证文章状态是否符合您的预期工作流程
• 确保数据库操作成功完成

如何通过 Webhook 接收文章数据？

概述