SuperAPI AI 工具集

upload-post-webhooks

编程与开发

查看项目

更新于 11-11 16:44

技能介绍

用途

该技能面向需要在自有服务中接收并处理 Upload-Post(upload-post.com)Webhook 的开发者。Upload-Post 是一个向多个社交网络发布内容的 API,其 Webhook 用于通知上传结果、社交账号连接状态变化,以及可选的 Instagram 私信和评论(涉及 Instagram、TikTok、LinkedIn Company Pages)。

主要能力

  • 校验 X-Upload-Post-Signature 请求头,防止伪造请求。
  • 解析并分发常见事件类型:
    • upload_completed:上传完成(含各平台结果)。
    • social_account_connected:社交账号连接到某个 profile。
    • social_account_disconnected:社交账号断开(含原因)。
    • social_account_reauth_required:已连接账号需要重新授权。
    • dm_received:收到 Instagram 私信(需主动开启)。
    • comment_received:收到 Instagram、TikTok 或 LinkedIn Company Page 账号的评论(需主动开启;Threads 正在逐步推出)。
  • 提供 Node 与 Python 的签名校验参考实现,并指向 Express、Next.js、FastAPI 的完整示例目录。
  • 附带参考文档:references/overview.md(概念、事件、投递行为)、references/setup.md(配置 Webhook URL 与密钥)、references/verification.md(签名校验细节与注意事项)。

使用方式

签名校验要点

Upload-Post 在账号配置了 webhook_secret 时发送两个头:

  • X-Upload-Post-Signature: sha256=<hex>
  • X-Upload-Post-Timestamp(Unix 秒)

签名是对 <timestamp>.<raw body> 计算的 HMAC-SHA256 小写十六进制值。

关键注意事项:

  • 密钥要整体使用,包括 whsec_ 前缀;Upload-Post 把它当作普通 HMAC 密钥(key),直接使用它的 UTF-8 字节,不做 base64 解码。因此不要使用 standardwebhooks 或 svix 库。
  • 构造待签名字节时:时间戳头按 latin1 编码,后接 .,再接原始请求体;不要对请求体做解码再编码。
  • 签名缺失、为空、格式不合法或校验不匹配时,应返回 401。
  • 获取原始请求体的方式:Express 用 express.raw({ type: '*/*' }),Next.js 用 await request.arrayBuffer(),FastAPI 用 await request.body();只有在校验通过后才解析 JSON。

Node 示例:

const crypto = require('crypto');

function verify(rawBody, signature, timestamp, secret) {
  if (!signature || !timestamp || !secret) return false;
  const hex = signature.startsWith('sha256=') ? signature.slice(7) : signature;
  if (!/^[0-9a-fA-F]{64}$/.test(hex)) return false;
  const signed = Buffer.concat([Buffer.from(timestamp, 'latin1'), Buffer.from('.'), rawBody]);
  const expected = crypto.createHmac('sha256', secret).update(signed).digest();
  const received = Buffer.from(hex.toLowerCase(), 'hex');
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

Python 示例:

import hashlib, hmac, re

def verify(raw_body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    if not signature or not timestamp or not secret:
        return False
    digest = signature[7:] if signature.startswith("sha256=") else signature
    if not re.fullmatch(r"[0-9a-fA-F]{64}", digest):
        return False
    signed = b"".join([timestamp.encode("latin-1"), b".", raw_body])
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).digest()
    return hmac.compare_digest(bytes.fromhex(digest.lower()), expected)

时间戳窗口(可选)

示例默认不拒绝旧时间戳。原因是 Hookdeck 的重试与重放会重新发送原始头,且 Hookdeck 自身不施加容差,固定窗口会拒绝合法重试。可通过环境变量 UPLOAD_POST_WEBHOOK_TOLERANCE_SECONDS(未设置或为 0 表示关闭)开启:超过该秒数与当前时间相差的投递将被拒绝。

另需注意:在密钥存在之前发出的投递不带签名头,会校验失败。

环境变量

UPLOAD_POST_WEBHOOK_SECRET=whsec_your_webhook_secret   # whole secret, whsec_ prefix included
UPLOAD_POST_WEBHOOK_TOLERANCE_SECONDS=0                # optional; 0 or unset = no timestamp window

本地开发

# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 upload-post --path /webhooks/upload-post

投递行为

每个事件只尝试投递一次,超时 10 秒。连接被拒绝或返回非 2xx 即视为事件丢失;连续 5 次失败后,该通道会暂停 30 分钟。建议快速响应并异步处理。

适用场景

  • 在自建后端接收 Upload-Post 的多平台上传结果通知。
  • 监听社交账号连接与断开、需要重新授权等账号状态变化。
  • 接入可选的 Instagram 私信与评论事件。
  • 需要正确实现 Upload-Post 特有 HMAC 校验逻辑的服务端开发。

限制与说明

  • 该技能不提供 Upload-Post 本身的发布 API 用法,仅聚焦 Webhook 接收与校验。
  • 事件负载字段需参考 Upload-Post 官方 Webhook 文档,本资料未列出全部字段。
  • 文档建议配合 webhook-handler-patterns 技能使用,以获得处理顺序(先校验、后解析、再幂等处理)、幂等、错误处理与重试逻辑的指导。
  • 使用该技能生成文件时,需在文件顶部添加注释:
// Generated with: upload-post-webhooks skill
// https://github.com/hookdeck/webhook-skills
  • 相关技能包括 tiktok-webhooks、facebook-webhooks、linkedin-webhooks、twitter-webhooks、zapier-webhooks、checkly-webhooks、github-webhooks、stripe-webhooks、webhook-handler-patterns、hookdeck-event-gateway。