Voltar para o blog

Notificações push no Supabase: um push no celular para cada novo cadastro ou pedido

Notificações push no Supabase: um push no celular para cada novo cadastro ou pedido

Seu app roda no Supabase, e os momentos que importam são linhas: um novo usuário em auth.users, um novo pedido em orders, uma assinatura que muda para canceled. Você só descobre isso quando abre o Table Editor, que num dia bom é à noite e num dia movimentado é na semana que vem.

O Supabase pode avisar você antes. Toda tabela pode chamar uma URL quando uma linha é inserida, atualizada ou excluída. Aponte essa chamada para o Pocket Alert e cada evento vira um push no seu celular, com o e-mail ou o valor do pedido no texto.

Este guia é sobre notificar você, o fundador ou administrador. Se você quer enviar notificações push para os usuários do seu próprio app, isso é trabalho para FCM, APNs ou Expo, e é outro artigo.

O que você precisa

  • Um projeto no Supabase que você consiga abrir no painel.
  • Uma conta no Pocket Alert e o app no seu celular iPhone ou Android. O plano gratuito basta para começar.

Se você construiu seu app com o Lovable e conectou o seu próprio projeto Supabase, tudo abaixo se aplica. No Lovable Cloud (o backend integrado) não existe o painel do Supabase, então o Nível 1 não tem onde rodar. O editor SQL dele (Database → Manage → SQL editor) oferece suporte a pg_net e Vault, então os triggers do Nível 2 são o caminho a tentar ali.

Nível 1: um Database Webhook, sem código

Os Database Webhooks do Supabase enviam uma requisição HTTP depois que uma linha muda em uma tabela. Os webhooks do Pocket Alert recebem JSON e o transformam em um push. Conectar os dois leva alguns minutos e não exige código.

Crie o webhook no Pocket Alert

Abra Webhooks no console do Pocket Alert e crie um:

  • Nome: Supabase. O título do push é sempre Webhook <name>, então este chega como "Webhook Supabase". Use um nome mais específico, como Supabase signups, se você planeja ter vários.
  • Mensagem: o template, explicado abaixo.

Copie a URL que o console mostra. Ela tem o formato https://p4a.me/wh/abc123xyz. O slug no final é o único segredo, então trate a URL inteira como uma senha.

Crie o webhook no Supabase

No painel do Supabase, abra seu projeto e vá em Integrations → Database Webhooks (guias mais antigos chamam de Database → Webhooks). Se a integração ainda não estiver ativada, ative-a primeiro; ela cria a função de trigger que os webhooks usam. Depois crie um novo webhook:

  1. Dê um nome, por exemplo notify_new_order.
  2. Escolha a tabela, por exemplo orders.
  3. Marque os eventos. Para alertas de "nova linha", marque apenas Insert.
  4. Escolha HTTP Request como tipo, método POST, e cole a URL do Pocket Alert.
  5. Deixe o cabeçalho Content-Type: application/json como está. O Pocket Alert só aceita corpos em JSON.

Salve. A partir daí, cada insert em orders envia uma requisição depois que a linha é gravada. O Supabase monta essas requisições com a extensão pg_net, que é assíncrona, então uma chamada de rede lenta nunca atrasa o próprio insert.

O que o Supabase envia

O corpo tem o mesmo formato para todas as tabelas:

{
  "type": "INSERT",
  "table": "orders",
  "schema": "public",
  "record": { "id": 1042, "email": "[email protected]", "total": 49, "status": "pending" },
  "old_record": null
}

record é a nova linha com todas as colunas. Em UPDATE, old_record guarda a linha como era antes; em DELETE, record é null e só old_record é preenchido.

O template da mensagem

De volta ao webhook do Pocket Alert, escreva a mensagem com placeholders %path% apontando para dentro desse JSON:

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

O próximo pedido chega assim:

Webhook Supabase
Nova linha em orders: #1042 · [email protected] · $49

Use qualquer coluna que sua tabela tenha: %record.plan%, %record.country%, %record.status%. Um * no lugar do template envia o JSON inteiro, o que ajuda enquanto você descobre os nomes das colunas.

O mesmo formulário tem um nível padrão. Defina high em um webhook de pedidos para que ele passe pelo Foco no iPhone, ou low em uma tabela movimentada que você só quer no histórico. O payload do Supabase não tem campo level, então o padrão do webhook é quem decide.

Cadastros de auth.users

O Supabase guarda os usuários em auth.users, e o seletor de tabelas dos Database Webhooks consegue selecioná-la: integrações como a Loops documentam exatamente essa configuração. Escolha a tabela de usuários no schema auth, marque Insert e use:

New signup: %record.email%

Se as tabelas de autenticação não aparecerem no seletor, ou se você preferir manter a lógica em SQL, o trigger da próxima seção também funciona em auth.users.

Onde o Nível 1 para

Um Database Webhook não tem condição. Marque Update em orders e você recebe um push toda vez que qualquer coluna muda: o status, o endereço de entrega, um updated_at alterado por um job em segundo plano. O template não consegue pular uma requisição; ele só a formata. Em uma tabela movimentada, isso é ruído na melhor das hipóteses, e na pior consome as 50 mensagens por dia do plano gratuito antes do almoço.

Para "me avise quando um pedido for pago" ou "me avise quando uma assinatura for cancelada", você precisa de um filtro, e o Postgres já tem um.

Nível 2: um trigger com pg_net e uma condição WHEN

Um Database Webhook é um trigger que chama o pg_net por você. Escrever o trigger você mesmo traz duas coisas: uma cláusula WHEN, para que o Postgres só dispare nas mudanças que importam, e controle total sobre a requisição, para que você possa chamar a API do Pocket Alert diretamente com seu próprio título, nível e botões.

Guarde a chave de API no Vault

Gere uma chave de API em Chaves de API e guarde-a no Supabase Vault pelo SQL Editor. Rode isso uma vez, fora das suas migrações, para que a chave nunca acabe em um arquivo:

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

Confirme que o pg_net está ativado em Database → Extensions. Projetos que usam Database Webhooks já o têm.

A função e o trigger

Isto envia um push somente quando o status de um pedido muda para paid:

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();

O que cada parte faz:

  • when (...) é o filtro que faltava no Nível 1. O Postgres nem chama a função a menos que o status tenha mudado de fato e o novo valor seja paid. Edições em outras colunas não custam nada.
  • security definer permite que a função leia o Vault. As roles que gravam linhas a partir do seu app, como authenticated, não conseguem, e sem isso as atualizações falhariam com erro de permissão. Este é o padrão descrito na documentação do Supabase.
  • net.http_post enfileira a requisição e retorna na hora; ela é enviada depois que a transação é confirmada. Se o update sofrer rollback, nenhum push sai.
  • level define o quão alto o aviso chega: default para eventos rotineiros, high para furar o Foco, critical para os que devem te acordar. Critical é um recurso pago; no plano gratuito ele é entregue como high.

Copie a função para outros eventos e mude a condição: new.status = 'canceled' em subscriptions, new.total > 500 em um trigger de insert para pedidos grandes, new.role = 'admin' em profiles.

Cadastros por um trigger em auth.users

O mesmo padrão em auth.users, com o provedor de login no texto:

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();

O Supabase avisa que um trigger com falha em auth.users pode bloquear cadastros. As chamadas coalesce evitam que um valor ausente quebre a string, e a requisição em si é assíncrona, então um push lento ou com falha não atrapalha o cadastro. Mesmo assim, teste uma vez com uma conta descartável antes de depender disso.

Ou uma Edge Function

Se você prefere TypeScript a PL/pgSQL, mantenha o Database Webhook do Nível 1, defina o tipo como Supabase Edge Functions e adicione o cabeçalho com a chave secreta que o formulário oferece. A função recebe o mesmo payload {type, table, record, old_record} e decide sozinha. O padrão do Supabase para chamadas com a chave secreta é o wrapper withSupabase com auth: 'secret', além de verify_jwt = false para a função em supabase/config.toml:

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");
  }),
};

Defina a chave com supabase secrets set POCKETALERT_API_KEY=.... O custo dessa abordagem: o webhook continua disparando em toda atualização, e a função filtra depois, então você paga uma invocação por mudança. O trigger com WHEN filtra antes de qualquer coisa rodar.

Limites honestos

  • Sem verificação de assinatura. O Pocket Alert não verifica de onde veio uma requisição do webhook; o slug da URL é o segredo. Se isso importa para você, use o trigger do Nível 2, que se autentica com sua chave de API.
  • A chave fica brevemente em uma tabela de fila. O Supabase observa que o pg_net mantém o cabeçalho descriptografado em net.http_request_queue até a requisição sair, e qualquer role que consiga fazer login no banco pode lê-lo ali.
  • O pg_net é de melhor esforço. As requisições ficam em tabelas unlogged, então uma queda no momento errado pode perder uma. Serve para "me avise sobre isso", não para cobrança.
  • Volume. Um trigger em uma tabela que recebe milhares de gravações por hora vai enviar milhares de pushes, a menos que a condição seja bem restrita. O plano gratuito permite 50 mensagens por dia.

Se nada chegar

  • Confira o histórico do webhook no Pocket Alert. Toda requisição para a URL do webhook fica registrada no console, com cabeçalhos, corpo, a mensagem renderizada e o status. Se a requisição estiver lá, o Supabase fez a parte dele e o problema está no template. Se não estiver, olhe o Supabase.
  • Confira o que o pg_net recebeu de volta. As respostas são mantidas por seis horas:
select status_code, content, error_msg, created
from net._http_response
order by created desc
limit 10;

Um 401 significa que a chave de API no Vault está errada; um 400 costuma indicar que o corpo não é um JSON válido ou que falta um campo.

  • Confira a condição do trigger. Rode à mão um update que deveria bater, como update orders set status = 'paid' where id = 1042;, e olhe net._http_response de novo.
  • Confira o evento. Um webhook que escuta só Insert não dispara em updates, e em DELETE os placeholders %record.*% ficam vazios porque a linha está em old_record.

Perguntas frequentes

Isso é o mesmo que enviar notificações push para os usuários do meu app?

Não. Isso envia pushes para o seu próprio celular pelo app do Pocket Alert. Os pushes para os dispositivos dos seus usuários passam por FCM, APNs ou um serviço como o Expo, que seu app precisa integrar por conta própria.

Dá para receber webhooks de banco de dados do Supabase só para uma coluna?

Não com o webhook do painel; ele dispara em qualquer mudança na linha. Um trigger com after update of status e uma condição WHEN, como no Nível 2, dispara somente quando essa coluna muda do jeito que você descreve.

Isso funciona no plano gratuito do Supabase?

Database Webhooks, triggers, pg_net e Vault fazem parte de um projeto Supabase normal, então nada aqui exige um plano pago do Supabase.

Dá para enviar tabelas diferentes para lugares diferentes?

Sim. Crie um webhook no Pocket Alert por tabela, cada um com seu nome, template e nível, ou coloque-os em aplicativos separados para que cadastros e pedidos cheguem em canais diferentes no app. Mais ideias em alertas de banco de dados e alertas de novos cadastros.

Preciso usar o webhook do Supabase?

Não. Qualquer coisa que consiga fazer POST de JSON pode usar um webhook do Pocket Alert, e qualquer coisa que consiga fazer uma chamada HTTP pode usar a API.

Crie uma conta gratuita, aponte uma tabela para ela, e o próximo cadastro vai aparecer na sua tela de bloqueio.

Compartilhe este artigo