免费开始
所有文章
从 Supabase 数据库流向安全本地 Webhook 端点的 Postgres 行插入、更新和删除事件。
Supabasedatabase webhooksPostgreslocal development

在 localhost 测试 Supabase Database Webhooks

在本地主机上测试 PPXTERM0001XPPPPPXTERM000XPP, 使用 host.docker.internal 当Supabase和接收器都运行在您的机器上时,或者当一个主机HTTPS项目必须调用您的本地应用程序时,使用公共HTTPSP隧道. 区别事项:当地PPXTERM0005XPP运行于Docker,其中 localhost 指数据库容器,虽然主机PPXTERM0007XPP需要互联网可访问的URL.

PPXTERM0009XPPPDatabase Webhooks发送

Database Webhooks 与 Postgres 反应 INSERT, (中文(简体) ). UPDATE,以及 DELETE 操作。 SupabaseP将其描述为在触发器周围的同步包裹. pg_net 扩展名。 更改行的交易不会等待您的接收者完成它的业务逻辑,它会减少耦合,但也意味着接收者必须能够被观察和意识到失败。

JSON有效载荷确定了操作、图和表,并包括行数据。 关于插入和更新, record 包含新行。 关于更新和删除, old_record 如果有,则提供上行。 围绕所记录的信封构建处理器,而不是将每个请求仅作为一行对象处理.

本地堆栈相对于主机项目

本地 Supabase 到本地应用程序:使用 Docker 主机

当你跑的时候 supabase start,Postgres在容器内. 网络浏览 URL 如 http://localhost:3000/api/supabase-db-hook 循环回容器,通常失败。 Supabase官方网站 页面存档备份,存于互联网档案馆 Database Webhooks 文档 告诉目标 host.docker.internal数字 :

http://host.docker.internal:3000/api/supabase-db-hook

这条路线不需要公共地道. 在没有主机名的Linux引擎上,如Supabase文件所建议,使用由您Docker设置所支持的主机出入口映射或您的机器的局域网地址. 从容器确认,而不只是从主机浏览器确认.

托管 Supabase 到本地应用程序: 使用 HTTPSP

云数据库无法解析您的笔记本 Docker主机名或私人回路地址. 启动本地应用程序并运行 npx portpreview 3000,然后配置 :

https://your-subdomain.portpreview.dev/api/supabase-db-hook

使用专用开发项目或低风险表. 一个"云"webhook可以包含真实的行数据,因此将生产表暴露在临时开发的URL上通常是一种差的测试策略.

创建验证共享密钥的接收器

与定义强制性HMAC头的提供者不同,Database Webhook是一个可配置外出HTTP请求. 在 Webhook 上保护端点并配置相同的端点 。 TLSP在中转时保护它;恒定时间比较避免通过您的应用程序泄露出密-前置时间.

// app/api/supabase-db-hook/route.ts
import crypto from 'node:crypto';

function safeEqual(a: string, b: string) {
  const left = Buffer.from(a);
  const right = Buffer.from(b);
  return left.length === right.length &&
    crypto.timingSafeEqual(left, right);
}

export async function POST(request: Request) {
  const supplied = request.headers.get('x-webhook-secret') ?? '';
  const expected = process.env.SUPABASE_DB_WEBHOOK_SECRET ?? '';

  if (!expected || !safeEqual(supplied, expected)) {
    return new Response('unauthorized', { status: 401 });
  }

  const payload = await request.json();
  if (!['INSERT', 'UPDATE', 'DELETE'].includes(payload.type)) {
    return new Response('unsupported event', { status: 400 });
  }

  await recordDelivery(payload);
  return new Response('accepted', { status: 200 });
}

共享头条可以证明对这个秘密的了解,但不以密码方式将该秘密与身体相接. 如果需要机体层面的篡改证据,将Database Webhook发送给一个能验证自身入境秘密的小型可信任的Edge Function,将你所选择的HMAC计算在犬类外出机体之上,并转发给当地或生产消费者. 不要发明一个 X-Supabase-Signature 假设,除非您自己的转发层创建并验证。

配置并触发一个焦点突出的 Webhook

  1. 选择一个开发表,并决定哪些操作很重要 。
  2. 在数据库 → Webhooks 下创建 Database Webhook,在 Supabase Dashboard 中选择 schema, table, 和操作.
  3. 设定上面描述的本地 Docker URL或公共地道URL.
  4. 添加 Content-Type: application/json 和随机 X-Webhook-Secret 可用 Webhook 页眉配置的值。
  5. 启动接收器并插入一个明显标记的测试行。
  6. 更新一个字段,然后删除行,验证所有选中的信封 。
  7. 在切换项目或关闭隧道前删除或禁用测试的 Webhook 。

命名测试行 所以清理是决定性的。 不要仅仅为了看到请求的到来而向生产客户记录点出全桌的集成。

安全翻译 INSERT, UPDATE, DELETEP

INSERT( 百花齐放)

使用 record 作为新插入的状态。 如果接收器在别处创建了相应的对象,则将源表的主键存储为一能键. 插入事件可以在手动回放或自定义重试处理时再次被交付.

UPDATEP (英语).

比较 record 与 old_record 并且只在与一体化有关的领域采取行动。 一般更新的webhook可能会为时间戳或无关的元数据发火. 过滤不开放业务的变化可以防止昂贵的下游呼叫.

DELETEP 页面存档备份,存于互联网档案馆.

删除的行由先前的数据来代表,而不是目前的记录. 让删除处理者容忍缺失的可选字段,并决定下游动作是删除,存档还是撤销. 保留审计要求.

switch (payload.type) {
  case 'INSERT':
    await mirror.upsert(payload.record.id, payload.record);
    break;
  case 'UPDATE':
    if (payload.old_record.status !== payload.record.status) {
      await syncStatus(payload.record.id, payload.record.status);
    }
    break;
  case 'DELETE':
    await mirror.archive(payload.old_record.id);
    break;
}

交货的可靠性是一个应用问题

由于Database Webhooks是一个同步的网络请求,所以不要将收件与发端行变化作为分布式交易处理. PostgresP承诺后,您的远程侧面可能无法使用. 监测出站请求结果,并设计任何无法丢失的调节。

对于高值的工作流程,一个出箱表更强:在一数据库交易中写出业务变更和出箱行,然后让工人交付带有明确的重试计数器,回放和死信处理. Database Webhook可以通知工人,但定期调节仍应找到未交付的出行.

使接机能发相. 一个有用的密钥将源代码、表、操作、主密钥和稳定行版本结合在一起,例如 updated_at; 对于严格的保证,在排出行中添加一个不可改变的事件PPXTERM00044XP. 避免只散列,因为两个有效的过渡可以产生相近的预测.

呼叫本地 Supabase PXTERM00045XPP

如果目的地是Edge Function,由当地Supabase堆栈服务,则有文献记载的例子是:

http://host.docker.internal:54321/functions/v1/my-function-name

官员 Edge Functions 开发指南 用途 supabase functions serve [function-name] 用于本地热重装。 Edge Functions 默认需要JWT 验证. 对于无法提供用户JWT的 Webhook 函数,请刻意配置该函数,例如: verify_jwt = false 内 supabase/config.toml,载于 函数配置。将 JWT 认证替换为您的秘密标题或签名检查;仅取消 JWT 功能即可公开。

Supabase Webhook 本地主机发送

本地堆栈拒绝连接

替换 localhost 与 host.docker.internal,验证应用绑定在Docker可到达的接口上,并确认端口. 在Linux上,配置主机出入口分辨率或使用主机IP. 仅与出乎意料的接口相连接的服务仍可能拒绝集装箱运输。

主机项目从未到达路线

一个主机项目需要公共HTTPS隧道URL,而不是Docker主机名. 确认隧道是直播的,其URL包括了完整路线. 自己贴入DNS/TLS.

路径返回 401

比较所配置的标题名称和值,监视引导或跟踪白空间,并在改变环境变量后重新启动应用程序. 记录信头是否存在, 绝不是其值 。 如果中介机构脱去自定义头, 请使用常规 Authorization: Bearer ... 正面并明确验证它。

有效载荷形状似乎不对

只记录顶级密钥, 操作, 计划, 和开发中的表格 。 记住DELETE使用上行数据,UPDATE可以包括两个版本. 根据当前官方有效载荷实例进行验证,然后修改您的参数 。

数据库更新成功但下游工作缺失

这种行为在同步设计中是可能的. 检查 Webhook 请求日志和 pg_net 在您环境中可用的诊断,然后添加重试或调节,而不是将已经承诺的商业交易卷回。

安全检查清单

  • 将HTTPS用于主机对本地测试,并自后旋转临时共享密钥.
  • 仅发送必要的列;避免暴露出敏感表或广泛的生产有效载荷.
  • 在剖析或活化尸体之前验证一个秘密标题。
  • 应用 POST 唯一的路由,请求大小限制,速率控制,以及被修改的日志.
  • 使用单独的本地, 中继, 和制作的网钩配置 。
  • 为重要事件建立明确的复议、公正、监督和调节机制。
  • 隧道关闭时禁用临时云 Webhook URL 。

最常见的本地错误是网络地址,而不是 PostgresP: 本地- 容器调用 host.docker.internal;云调用用公道. 一旦交通到达,将认证和交付担保作为单独的设计问题处理. 审查 本地主机隧道安全 和 Webhook 可靠性模式 在连接敏感数据之前。

常见问题

P (中文(简体) ). 为什么一个PPXTERM0001XPPPPXTERM0000XPP没有到达本地主机?
页面存档备份,存于互联网档案馆 本地PPXTERM0003XPPPostgres在Docker中运行,所以本地主机指容器. 使用 PPXTERM0002XPP 或您的主机IP 。 一个托管的PPXTERM0004XPP项目需要公共的PPXTERM0007XPP隧道URL.
P 双相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相 我需要一个隧道 本地PPXTERM0009XPPDatabase Webhooks?
P 高压电源 当Supabase和接收器均为本地时不使用;使用Docker主机路由. 当主机Supabase项目必须调用运行在您的计算机上的应用程序时,您需要一条隧道 。
P 高压电源 SupabaseDatabase Webhooks是自动签名的吗?.
存档副本 不要假定一个提供商HMAC头. 配置和验证共享的秘密头 。 如果您需要带有正文的签名, 请通过一个可信任的函数转发, 以创建 HMACP, 您的接收器将验证 。
P (英语). SupabasePPTERM00017XPP发送什么数据?
P (英语). JSON信封识别出PPXTERM000019XPP,PPXTERM000020XPP,或PPXTERM000021XPP+图和表. 它包括插入和更新的新记录以及可供更新或删除的前行数据。