# Supabase 推送通知：新注册或新订单，手机上即时收到一条推送

> 数据库中有新记录时，手机立即收到推送。用 Database Webhook 无需代码即可通知新注册和新订单；用 Postgres 触发器加 pg_net 监听状态变化，并设置优先级和可打开表格的按钮。

*24.10.2026*

<!-- source: https://pocketalert.app/zh/blog/supabase-push-notifications -->

你的应用运行在 Supabase 上，你真正关心的时刻都体现在数据行里：`auth.users` 里多了一个新用户，`orders` 里多了一笔新订单，某个订阅变成了 `canceled`。你通常要打开 Table Editor 才能发现这些变化，好的时候是当天晚上，忙的时候可能要等到下周。

Supabase 可以更快地告诉你。每张表都可以在行被插入、更新或删除时调用一个 URL。把这个调用指向 Pocket Alert，每个事件都会变成你手机上的一条推送，文本里还包含邮箱或订单金额。

本指南讲的是通知**你**，也就是创始人或管理员本人。如果你想给应用自己的用户发推送，那需要用 FCM、APNs 或 Expo，是另一篇文章的内容。

## 你需要准备

- 一个能在控制台中打开的 Supabase 项目。
- 一个 Pocket Alert 账号，以及手机上的 [iPhone 或 Android](/get-app) 应用。免费套餐就够用了。

如果你的应用是用 Lovable 搭建并连接了自己的 Supabase 项目，下面的内容都适用。如果使用的是 Lovable Cloud（内置后端），则没有 Supabase 控制台，所以第一级无法操作。它的 SQL 编辑器（**Database → Manage → SQL editor**）确实支持 `pg_net` 和 Vault，你可以在那里尝试第二级的触发器。

## 第一级：Database Webhook，无需代码

Supabase Database Webhook 会在表中的数据行发生变化后发送一个 HTTP 请求。Pocket Alert 的 Webhook 接收 JSON 并将其转换为推送。把两者连接起来只需几分钟，无需写代码。

### 创建 Pocket Alert Webhook

在 Pocket Alert 控制台中打开 [Webhooks](/webhooks) 并创建一个：

- **名称：** `Supabase`。推送标题始终为 `Webhook <name>`，所以这个会显示为「Webhook Supabase」。如果你打算创建多个，可以用更具体的名称，比如 `Supabase signups`。
- **消息：** 模板，下文会讲。

复制控制台显示的 URL，格式类似 `https://p4a.me/wh/abc123xyz`。末尾的 slug 是唯一的密钥，所以请把整个 URL 当作密码对待。

### 创建 Supabase Webhook

在 Supabase 控制台中打开你的项目，进入 **Integrations → Database Webhooks**（较旧的教程里称为 Database → Webhooks）。如果尚未启用该集成，先启用它；它会创建 Webhook 所用的触发器函数。然后新建一个 Webhook：

1. 填写名称，例如 `notify_new_order`。
2. 选择表，例如 `orders`。
3. 勾选事件。若只需要「新行」提醒，只勾选 **Insert**。
4. 类型选择 **HTTP Request**，方法为 `POST`，并粘贴 Pocket Alert 的 URL。
5. 保留 `Content-Type: application/json` 请求头不变。Pocket Alert 只接受 JSON 请求体。

保存即可。此后，每次向 `orders` 插入数据，在行写入之后都会发送一个请求。Supabase 使用 `pg_net` 扩展发送这些请求，它是异步的，所以网络调用的慢速不会阻塞插入操作本身。

### Supabase 会发送什么

请求体对每张表的结构都相同：

```json
{
  "type": "INSERT",
  "table": "orders",
  "schema": "public",
  "record": { "id": 1042, "email": "ana@example.com", "total": 49, "status": "pending" },
  "old_record": null
}
```

`record` 是新行的全部列。对于 `UPDATE`，`old_record` 保存变更前的行；对于 `DELETE`，`record` 为 `null`，只有 `old_record` 有值。

### 消息模板

回到 Pocket Alert 的 Webhook，用指向上述 JSON 的 `%path%` 占位符编写消息：

```text
New %table% row: #%record.id% · %record.email% · $%record.total%
```

下一笔订单到达时会显示为：

> **Webhook Supabase**
> New orders row: #1042 · ana@example.com · $49

你的表中有任何列都可以使用，例如 `%record.plan%`、`%record.country%`、`%record.status%`。如果用 `*` 代替模板，就会发送整个 JSON，在你摸清列名的时候很有帮助。

这个表单还有**默认级别**。在 orders 的 Webhook 上设置 `high`，让它能穿透 iPhone 上的专注模式；在一张繁忙、只想留在历史记录里的表上设置 `low`。Supabase 的 payload 没有 `level` 字段，所以由 Webhook 的默认值决定级别。

### auth.users 的新注册

Supabase 把用户存在 `auth.users` 里，Database Webhook 的表选择器可以选中它：Loops 等集成文档中就有这种设置。选择 `auth` schema 下的用户表，勾选 **Insert**，然后使用：

```text
New signup: %record.email%
```

如果你的选择器里没有出现 auth 表，或者你更希望把逻辑放在 SQL 中，下一节的触发器同样适用于 `auth.users`。

## 第一级的局限

Database Webhook 没有条件判断。在 `orders` 上勾选 **Update**，那么任何一列变化都会推送一次：状态、收货地址、被后台任务更新的 `updated_at`。模板无法跳过请求，它只负责格式化。在繁忙的表上，这至多是噪音，严重时会在午饭前就耗尽免费套餐每天 50 条的额度。

如果你想要「订单变为已支付时通知我」或「订阅被取消时通知我」，就需要过滤条件，而 Postgres 本身就提供了这种能力。

## 第二级：带 WHEN 条件的 pg_net 触发器

Database Webhook 本质上是替你调用 `pg_net` 的触发器。自己编写触发器能得到两个好处：一是 `WHEN` 子句，使 Postgres 只在你关心的变化上触发；二是完全掌控请求，可以直接调用 Pocket Alert API，自定义标题、级别和按钮。

### 把 API 密钥存入 Vault

从 [API Keys](/account/apikeys) 获取一个 API 密钥，然后在 SQL Editor 中把它存入 Supabase Vault。在迁移脚本之外运行一次即可，这样密钥就不会出现在任何文件中：

```sql
select vault.create_secret('YOUR_POCKETALERT_API_KEY', 'pocketalert_key');
```

确保在 **Database → Extensions** 中启用了 `pg_net`。已经使用 Database Webhook 的项目默认已启用。

### 函数与触发器

下面的代码只在订单状态变为 `paid` 时发送推送：

```sql
create or replace function public.notify_order_paid()
returns trigger
language plpgsql
security definer
set search_path = ''
as $$
begin
  perform net.http_post(
    url := 'https://api.pocketalert.app/v1/messages',
    headers := jsonb_build_object(
      'Content-Type', 'application/json',
      'Token', (select decrypted_secret from vault.decrypted_secrets where name = 'pocketalert_key')
    ),
    body := jsonb_build_object(
      'title', 'Order paid: $' || new.total,
      'message', '#' || new.id || ' · ' || coalesce(new.email, 'no email'),
      'level', 'high',
      'actions', jsonb_build_array(jsonb_build_object(
        'type', 'view',
        'label', 'Open orders',
        'value', 'https://supabase.com/dashboard/project/YOUR_PROJECT_REF/editor'
      ))
    )
  );
  return new;
end;
$$;

create trigger on_order_paid
after update of status on public.orders
for each row
when (old.status is distinct from new.status and new.status = 'paid')
execute function public.notify_order_paid();
```

各部分的作用：

- **`when (...)`** 就是第一级所缺少的过滤条件。除非状态确实发生了变化且新值为 `paid`，Postgres 甚至不会调用该函数。修改其他列不会产生任何开销。
- **`security definer`** 让函数能够读取 Vault。像 `authenticated` 这类从你的应用写入数据行的角色无法读取 Vault，如果没有这个设置，它们的更新会因权限错误而失败。这是 Supabase 文档中的标准写法。
- **`net.http_post`** 会把请求加入队列并立即返回，请求在事务提交后才发出。如果更新被回滚，就不会发出任何推送。
- **`level`** 决定通知的提醒强度：`default` 用于常规事件，`high` 用于穿透专注模式，`critical` 用于需要把你叫醒的事件。`critical` 是付费功能，在免费套餐中会按 `high` 投递。

如需其他事件，复制这个函数并修改条件即可：在 `subscriptions` 上使用 `new.status = 'canceled'`，在插入触发器上使用 `new.total > 500` 来监控大额订单，在 `profiles` 上使用 `new.role = 'admin'`。

### 通过 auth.users 上的触发器发送注册通知

同样的写法用在 `auth.users` 上，并在文本中加入登录提供方：

```sql
create or replace function public.notify_new_signup()
returns trigger
language plpgsql
security definer
set search_path = ''
as $$
begin
  perform net.http_post(
    url := 'https://api.pocketalert.app/v1/messages',
    headers := jsonb_build_object(
      'Content-Type', 'application/json',
      'Token', (select decrypted_secret from vault.decrypted_secrets where name = 'pocketalert_key')
    ),
    body := jsonb_build_object(
      'title', 'New signup',
      'message', coalesce(new.email, 'no email') || ' via ' || coalesce(new.raw_app_meta_data ->> 'provider', 'unknown')
    )
  );
  return new;
end;
$$;

create trigger on_auth_user_created_notify
after insert on auth.users
for each row execute function public.notify_new_signup();
```

Supabase 提醒，`auth.users` 上失败的触发器可能会阻止注册。`coalesce` 调用可以防止缺失的值破坏字符串，而且请求本身是异步的，所以推送的慢速或失败不会影响注册流程。不过，在依赖它之前，请先用一个临时账号测试一次。

### 或者使用 Edge Function

如果你更喜欢 TypeScript 而不是 PL/pgSQL，保留第一级的 Database Webhook，把类型设为 **Supabase Edge Functions**，并添加表单中提供的 secret key 请求头。函数会收到相同的 `{type, table, record, old_record}` 载荷，并自行判断。Supabase 推荐使用带有 `auth: 'secret'` 的 `withSupabase` 包装器来处理带 secret key 的调用，同时在 `supabase/config.toml` 中为该函数设置 `verify_jwt = false`：

```ts
import { withSupabase } from "npm:@supabase/server@1";

export default {
  fetch: withSupabase({ auth: "secret" }, async (req) => {
    const { type, record, old_record } = await req.json();
    if (type !== "UPDATE" || record.status === old_record.status) {
      return new Response("skipped");
    }

    await fetch("https://api.pocketalert.app/v1/messages", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Token: Deno.env.get("POCKETALERT_API_KEY")!,
      },
      body: JSON.stringify({
        title: `Order #${record.id}: ${record.status}`,
        message: `${record.email} · $${record.total}`,
        level: record.status === "refunded" ? "high" : "default",
      }),
    });
    return new Response("ok");
  }),
};
```

使用 `supabase secrets set POCKETALERT_API_KEY=...` 设置密钥。这种方式的取舍是：Webhook 仍然会在每次更新时触发，函数再事后过滤，因此每次变更都会产生一次函数调用费用。而 `WHEN` 触发器会在任何代码运行之前完成过滤。

## 诚实的局限

- **没有签名校验。** Pocket Alert 不会验证 Webhook 请求的来源，URL 中的 slug 就是密钥。如果这一点很重要，请使用第二级的触发器，它通过你的 API 密钥进行身份验证。
- **密钥会短暂停留在队列表中。** Supabase 指出，`pg_net` 会把解密后的请求头保存在 `net.http_request_queue` 中，直到请求发出为止，任何能登录数据库的角色都可以在那里读取到它。
- **pg_net 是尽力而为。** 请求保存在未记录日志的表中，因此在不恰当的时刻发生崩溃可能会丢失一条请求。用于「告诉我一声」很合适，但不适合用于计费相关场景。
- **数据量。** 如果某张表每小时有数千次写入，除非条件足够精确，触发器会发送数千条推送。免费套餐每天只允许 50 条消息。

## 如果没有收到通知

- **检查 Pocket Alert 的 Webhook 历史记录。** 发往 Webhook URL 的每个请求都会在控制台中记录，包括请求头、请求体、渲染后的消息和状态。如果记录存在，说明 Supabase 已经完成了它的部分，问题出在模板上。如果记录不存在，请检查 Supabase。
- **检查 pg_net 返回了什么。** 响应会保留六小时：

```sql
select status_code, content, error_msg, created
from net._http_response
order by created desc
limit 10;
```

`401` 表示 Vault 中的 API 密钥有误；`400` 通常表示请求体不是合法的 JSON，或者缺少某个字段。

- **检查触发器条件。** 手动执行一条应该匹配的更新，例如 `update orders set status = 'paid' where id = 1042;`，然后再次查看 `net._http_response`。
- **检查事件类型。** 只监听 Insert 的 Webhook 不会在更新时触发；而在 `DELETE` 时，`%record.*%` 占位符为空，因为数据行保存在 `old_record` 中。

## 常见问题

### 这和给我应用的用户发推送是一回事吗？

不是。这里是通过 Pocket Alert 应用把推送发到你自己的手机上。发给用户设备的推送要通过 FCM、APNs 或 Expo 之类的服务，需要你的应用自行集成。

### 能否只为某一列获取 Supabase 数据库 Webhook 通知？

控制台中的 Webhook 做不到，它会在数据行的任何变化时触发。像第二级那样，使用带 `after update of status` 和 `WHEN` 条件的触发器，就只会在该列按你描述的方式变化时触发。

### 这在 Supabase 免费套餐上能用吗？

Database Webhook、触发器、`pg_net` 和 Vault 都是普通 Supabase 项目的一部分，所以这里的内容都不需要付费的 Supabase 套餐。

### 能否把不同的表发送到不同的地方？

可以。为每张表创建一个 Pocket Alert Webhook，各自设置名称、模板和级别；或者放到不同的应用中，让注册和订单在应用里进入不同的频道。更多思路请参阅[数据库告警](/use-cases/database-alerts)和[注册告警](/use-cases/signup-alerts)。

### 必须使用 Supabase 的 Webhook 吗？

不必。任何能发送 POST JSON 的东西都可以使用 [Pocket Alert Webhook](/tools/webhook)，任何能发起 HTTP 调用的程序都可以使用 API。

[免费注册账号](/signup)，把一张表指向它，下一次有人注册时，通知就会出现在你的锁屏上。
