Webhooks 集成

Webhook 允许 PicFast 在发生特定事件（如图片上传、删除或审核决策）时，向外部服务（如 n8n、Make、Zapier 或你的应用程序）发送实时 HTTP 通知。

创建 Webhook

  1. 在 PicFast 控制台侧边栏中进入 Webhooks
  2. 点击 新建 Webhook
  3. 输入名称、目标 URL（必须是 HTTPS）并选择一个或多个事件类型
  4. 立即复制密钥 — 关闭后将无法再次查看

支持的事件

事件类型说明
image.uploaded图片上传成功
image.processed处理流水线完成（压缩、缩略图、审核）
image.deleted图片被删除（所有者、管理员或过期清理）
moderation.reviewed管理员通过或拒绝了图片
user.registered新用户注册

验证签名

PicFast 使用 HMAC-SHA256 对每次投递进行签名。签名头为 X-PicFast-Signature: sha256=...。使用创建时返回的 webhook 密钥进行验证：

import crypto from 'crypto'

function verifySignature(secret, timestamp, rawBody, signature) {
  const payload = `${timestamp}.${rawBody}`
  const hmac = crypto.createHmac('sha256', secret)
  hmac.update(payload)
  const expected = `sha256=${hmac.digest('hex')}`
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
}

// 在 HTTP handler 中：
const sig = req.headers['x-picfast-signature']
const ts = req.headers['x-picfast-timestamp']
if (Math.abs(Date.now()/1000 - parseInt(ts)) > 300) {
  return res.status(400).send('时间戳已过期')
}
if (!verifySignature(secret, ts, JSON.stringify(req.body), sig)) {
  return res.status(401).send('签名无效')
}

投递与重试

PicFast 在投递失败时使用指数退避进行重试：

尝试次数延迟
1立即
21 分钟
35 分钟
430 分钟
52 小时
612 小时

6 次失败后，投递标记为死信。可以在 webhook 详情页手动重放任何失败的投递。

请求头

请求头说明
X-PicFast-Event-Id唯一事件实例 UUID
X-PicFast-Event-Type事件类型（如 image.uploaded）
X-PicFast-Delivery-Id唯一投递尝试 ID
X-PicFast-Timestamp签名生成的 Unix 时间戳
X-PicFast-SignatureHMAC-SHA256 签名

n8n 集成

  1. 在 n8n 工作流中添加 Webhook 节点（HTTP 方法：POST）
  2. 复制 n8n 的生产 Webhook URL
  3. 在 PicFast 中创建一个指向 n8n URL 的 webhook 并选择事件类型
  4. 在 n8n 中将 Webhook 节点连接到处理逻辑
  5. 使用 PicFast 中的 测试 按钮验证连通性