用途:接收并校验 Supabase 发出的出站 Webhook,涵盖数据库 Webhook 与 Auth Hooks(HTTP Hook)两类系统;两者不共用安全模型,不可混用校验方式。
主要能力与区别:数据库 Webhook 由 Postgres 触发器经 pg_net 触发,事件仅有 INSERT、UPDATE、DELETE,无 HMAC 签名、无签名密钥、无 Supabase 专有头部,鉴权靠创建 Webhook 时自行配置的请求头(如 Authorization: Bearer …),需常量时间比较;语义为异步即发即弃,文档未说明重试,投递历史存于数据库 net schema,去重由接收方按 record/old_record 主键自行处理。载荷固定为 type(大写)、table、schema、record、old_record 五个顶层字段。
Auth Hooks 由 Supabase Auth(GoTrue)发出,采用 Standard Webhooks HMAC-SHA256,使用 webhook-id / webhook-timestamp / webhook-signature 头;密钥格式为 v1,whsec_<base64>,需去掉前缀后交给 standardwebhooks 库验证,且必须传入原始请求体。含六个钩子:before_user_created、custom_access_token、send_sms、send_email、mfa_verification_attempt、password_verification_attempt,属请求/响应语义,部分钩子在免费与 Pro 计划可用,mfa_verification_attempt 与 password_verification_attempt 限 Teams 与 Enterprise。错误为状态码 ≥400;429 或 503 仅在返回非空 retry-after 头时最多重试三次、退避 2 秒、总预算 5 秒。
使用方式:可在 Dashboard(Integrations → Webhooks)或 SQL 中用 supabase_functions.http_request 创建触发器;本地调试可用 npx hookdeck-cli listen 3000 supabase --path /webhooks/supabase 与 npx hookdeck-cli listen 3000 supabase-auth-hook --path /webhooks/supabase/auth-hook,两类需分别开隧道。环境变量为 SUPABASE_AUTH_HOOK_SECRET(含 v1,whsec_ 前缀)与自行生成的 SUPABASE_WEBHOOK_SECRET。示例处理器见 examples/express/、examples/nextjs/、examples/fastapi/。
限制:Supabase 未提供来源 IP 允许列表与 user-agent 值,不应据此写接收端;Auth Hooks 也可配为 Postgres 函数(pg-functions://…),此时无 HTTP 请求,上述规则不适用。