OpenMontage FLUX 图像生成 Webhook 回调实战：从签名校验到轮询兜底的 4 个生产决策
项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage 凌晨，OpenMontage 的生产队列里堆了 400 个 FLUX 出图任务，每个都在循环请求 polling_url，三分钟后 429 限流打过来，一半任务带着未知状态直接挂了。这是拿轮询扛事件驱动场景的典型代价：BFL 的 FLUX API 是异步生成，提交后只给你一个 polling_url，得自己等。但官方早给了另一条路——生成完让它主动"上门"，也就是 Webhook（回调）模式。这篇文章把这条回调链路走一遍：怎么挂到请求上、怎么给回调端点上签名锁、怎么挡住重复投递，以及三次重试耗尽后该去哪找结果。
BFL 的"门铃"是怎么工作的
理解回调机制，先把它想成快递：轮询是你隔一会儿就跑一趟驿站问"我的件到了没"；Webhook 是骑手把件放到门口货架、再按你家门铃，你听到铃声才去看。差别有两个：你不再需要出门问，而且件到手的瞬间你就知道了，不用等下一个问询间隔。
落到 BFL 上就是：生成结束后，它向你注册的 webhook_url 发一次 POST，负载只有两种形态。成功时 status 为 "Ready"，图片地址在 result.sample 里，类似 {"id": "gen_abc123", "status": "Ready", "result": {"sample": "https://..."}}；失败时 status 为 "Error"，原因在 error 字段，类似 {"id": "gen_abc123", "status": "Error", "error": "content_policy_violation", "message": "..."}。
端点本身有三条硬约束，都写在仓库的 webhook-integration.md 里：URL 必须是 HTTPS，BFL 不会向 HTTP 地址发回调；30 秒内用 2xx 应答；回调函数里别干重活，下载、写库、通知下游全部卸到队列。投递失败的回调会按 1 秒、5 秒、30 秒的节奏重试三次，再失败就放弃——记住"三次"这个数字，它是后文兜底设计的触发条件。
提交请求时挂上门铃
先说提交端，改动小到可以忽略：请求体里多带两个字段就行。
curl -X POST "https://api.bfl.ai/v1/flux-2-pro" \
-H "x-key: $BFL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A beautiful sunset over mountains",
"webhook_url": "https://your-server.com/api/bfl-webhook",
"webhook_secret": "your-secret-key-here"
}'
webhook_url 决定"铃按到哪"，webhook_secret 决定"怎么证明是 BFL 在按"。后者可选，但不传的话 BFL 不会对回调签名，等于任何能访问你端点的人都伪造得了回调。仓库里的 python-client.py 客户端也是同样处理：只有两个参数非空时才写进 payload，签名校验函数 verify_webhook_signature 也在同一文件里，可以作为你实现的对照版。
签名锁：只认带签名的敲门
传了 secret 之后，BFL 会用 HMAC-SHA256（哈希消息认证码）对原始请求体算摘要，放在请求头 X-BFL-Signature: sha256=<十六进制摘要>。校验本质就是重算再比对，核心只有几行：
import hmac, hashlib
def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
if not signature or not signature.startswith("sha256="):
return False
expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature[7:]) # 恒定时间比较
有两行最值得盯：传入的 payload 必须是请求体的原始字节——Python 里是 request.data，Express 里要 express.raw 留住 Buffer，先 JSON.parse 再序列化一次，键序和空白一变摘要就对不上；比较用的是 hmac.compare_digest 而不是 ==，普通相等比较的耗时差异会泄露前缀匹配信息，让签名可以逐字节猜。
幂等闸门：同一个 id 只处理一次
因为存在重试，同一个回调可能到两三次，回调端必须幂等（idempotent）——同样的输入只产生一次副作用。最省事的实现是 Redis 的"不存在才写入"：
def is_duplicate(generation_id: str) -> bool:
# nx: 仅当键不存在时写入；ex: 1 小时后自动过期，防内存无限增长
was_set = redis_client.set(f"webhook:processed:{generation_id}", "1",
nx=True, ex=3600)
return not was_set # 写入失败 = 重复投递
去重键直接用负载里的 id（生成编号），TTL 取 1 小时：既盖住三轮重试的窗口，又不会让键长期滞留。还有一条容易被漏掉：命中重复时照样回 200。回 4xx/5xx 会被 BFL 判定为投递失败，触发下一轮重试，你反而多干活。这个思路和工具层 flux_image.py 里声明 idempotency_key_fields 的做法一脉相承——整个工程体系都把"同一输入只生效一次"当默认约束。
门铃没响的时候去哪找
回调链路再稳也有翻车时刻：网络抖动、Pod 重启、handler 超时。BFL 的三次重试（1s/5s/30s）是缓冲不是承诺，耗尽之后结果不会自己来，你得去取。好在提交响应里始终带着 polling_url，按仓库 polling-patterns.md 的退避策略（指数退避（exponential backoff）加随机抖动，避免并发轮询同时打过去的惊群效应）去查就行。混合模式就是"先等铃响，超时没响再出门查"：
def generate(prompt, timeout=300):
resp = submit(prompt, webhook_url, webhook_secret) # 返回 id 与 polling_url
result = wait_for_webhook(resp["id"], timeout=timeout)
if result is None: # 铃没响，回退到轮询
result = poll(resp["polling_url"], timeout=60)
return result
⚠️ 还有个时间陷阱藏在成功负载里：result.sample 指向的图片 URL 生成后 10 分钟就失效。所以回调处理器拿到 "Ready" 后要立刻把图下载进自己的存储，再更新数据库、通知下游——把 URL 记进日志不等于拿到了图。
失败回调也别无脑重发，先分流。仓库 error-handling.md 给了现成的判断口径：
| 错误码 | 能否重试 | 处理动作 |
|---|---|---|
| content_policy_violation | 否 | 改提示词后重新提交 |
| invalid_image | 否 | 检查输入图后重新提交 |
| generation_timeout / internal_error | 是 | 指数退避重试或降级模型 |
给你的场景挑一个模式
三种姿势不是谁替代谁，而是各管一段：
| 场景 | 选择 | 理由 |
|---|---|---|
| 脚本、CLI、本地开发、单次请求 | 轮询 | 简单、无需公网端点、到处能跑 |
| 生产、高并发、服务器到服务器 | Webhook | 事件驱动、零重复调用、即时通知 |
| 不允许丢结果的核心任务 | Webhook + 轮询兜底 | 投递失败时自动找回结果 |
实操节奏：先用轮询把业务跑通，任务量上来、需要即时通知时再挂 webhook_url 和签名锁，核心任务补上超时回退。签名密钥、恒定时间比较、幂等去重、超时兜底这四个决策，单看都是几行代码的事，合起来才是"回调在 demo 里能跑"和"夜里不炸"的全部距离。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
