A integração com o Supabase envia os emails do Supabase Auth pelo Notifuse e sincroniza os novos usuários com os seus contatos.
Visão geral
Ela tem duas partes:
- Auth Email Hook: envia os emails transacionais dos eventos de autenticação (cadastro, magic link, recuperação de senha etc.)
- Before User Created Hook: adiciona os novos usuários do Supabase aos seus contatos do Notifuse
Configuração
Vá em Configurações → Integrações, clique em Adicionar integração e escolha Supabase em Apps conectados.
Pré-requisitos
Você precisa de:
- Um workspace do Notifuse com as permissões necessárias
- Um projeto do Supabase
- Pelo menos uma integração de email configurada no Notifuse (para enviar os emails transacionais)
Auth Email Hook
O Auth Email Hook envia os seus próprios emails de autenticação pelo Notifuse no lugar dos emails padrão do Supabase.
Como configurar
- Vá em Supabase Auth Hooks no seu Supabase Dashboard e abra as configurações do Auth Email Hook
- Adicione um novo hook
- Selecione o tipo “HTTPS”
- Clique em “Generate a secret” e copie o valor para a integração no Notifuse
- Salve a integração para ver o endpoint de webhook gerado pelo Notifuse
- Cole o endpoint de webhook no seu hook do Supabase e salve
Templates padrão
Na primeira vez que você salva a integração com o Supabase, o Notifuse cria um template padrão para cada tipo de email. Esses templates:
- São marcados como gerenciados pela integração (não podem ser excluídos)
- Incluem todas as variáveis de template Liquid necessárias vindas do Supabase
- Podem ser editados para seguir a sua marca
Variáveis de template
Todos os templates de email de autenticação do Supabase têm acesso a estas variáveis:
{# User information #}
{{ user.id }}
{{ user.email }}
{{ user.phone }}
{{ user.email_new }} {# Only for email change #}
{# Email data #}
{{ email_data.token }} {# OTP code (for display, not URLs) #}
{{ email_data.token_hash }} {# Hashed token for verification URLs #}
{{ email_data.token_new }} {# For secure email changes #}
{{ email_data.token_hash_new }} {# For secure email changes #}
{{ email_data.redirect_to }} {# Where to redirect after verification #}
{{ email_data.site_url }} {# Your Supabase auth URL #}
{{ email_data.email_action_type }} {# Type: signup, recovery, magiclink, etc. #}
Formato da URL de confirmação
Os links de confirmação precisam usar exatamente este formato para funcionar com o sistema de autenticação GoTrue do Supabase:
{{ email_data.site_url }}/verify?token={{ email_data.token_hash }}&type={{ email_data.email_action_type }}&redirect_to={{ email_data.redirect_to }}
O resultado é uma URL como esta:
https://yourproject.supabase.co/auth/v1/verify?token=abc123...&type=signup&redirect_to=https://yourapp.com
Use token_hash na URL, e não token. A variável token serve para exibir códigos OTP nos emails de reautenticação.
Exemplo de template
Um template de confirmação de cadastro com o formato de URL correto:
<mjml>
<mj-body>
<mj-section>
<mj-column>
<mj-text font-size="20px" color="#F45E43" font-family="Helvetica"> Welcome! </mj-text>
<mj-text font-size="16px" color="#555" font-family="Helvetica">
Please confirm your email address by clicking the link below:
</mj-text>
<mj-button
href="{{ email_data.site_url }}/verify?token={{ email_data.token_hash }}&type={{ email_data.email_action_type }}&redirect_to={{ email_data.redirect_to }}"
background-color="#F45E43"
color="white"
>
Confirm Email
</mj-button>
<mj-text font-size="14px" color="#555" font-family="Helvetica">
If you did not sign up for this account, you can ignore this email.
</mj-text>
</mj-column>
</mj-section>
</mj-body>
</mjml>
Before User Created Hook
O Before User Created Hook adiciona os novos usuários do Supabase aos seus contatos do Notifuse.
Como configurar
- Abra o painel Hook antes de criar usuário no formulário da integração com o Supabase
- Gere uma chave secreta de webhook no Supabase (diferente da do Auth Email Hook)
- Cole a chave secreta no formulário da integração com o Supabase no Notifuse
- (Opcional) Selecione uma lista de contatos à qual adicionar os novos usuários
- (Opcional) Recuse endereços de email descartáveis (por exemplo, @yopmail.com)
Mapeamento de campos
Os campos de usuário do Supabase correspondem a estes campos de contato do Notifuse:
| Campo do Supabase | Campo do Notifuse |
|---|---|
email | email |
id | external_id |
phone | phone |
user_metadata | Campo Custom JSON configurável (opcional) |
Nas configurações da integração, você escolhe qual campo Custom JSON (1 a 5) recebe o user_metadata do Supabase. Se você não escolher nenhum, o user_metadata não é sincronizado.
Tratamento de erros
O Before User Created Hook nunca bloqueia um cadastro na sua aplicação. O erro é registrado no log e o cadastro continua quando:
- A gravação do contato falha
- A lista de contatos configurada foi excluída
Segurança
Verificação da assinatura do webhook
O Notifuse verifica cada webhook do Supabase pela assinatura HMAC-SHA256 e recusa os que têm assinatura inválida, então só processa requisições vindas do seu projeto do Supabase.
Criptografia
As chaves de assinatura dos webhooks são armazenadas criptografadas no banco de dados do Notifuse, com criptografia AES-256.
Testes
Testar os emails de autenticação
- Na sua aplicação, inicie um fluxo de autenticação (por exemplo, um cadastro)
- Confira nos logs do Notifuse se o webhook foi recebido
- Confira a caixa de entrada do destinatário
Testar a sincronização de usuários
- Crie um novo usuário no seu projeto do Supabase
- No Notifuse, vá em Contatos
- Procure o email do usuário para confirmar que ele foi adicionado
- Se você configurou uma lista de destino, confira se o usuário está nela
Solução de problemas
Os emails não são enviados
Verifique estes pontos:
- Há um Segredo do hook salvo no painel Hook de envio de email no Notifuse?
- A chave de assinatura do webhook está correta no Supabase e no Notifuse?
- Há um provedor de email transacional configurado no seu workspace?
- Procure mensagens de erro nos logs do Notifuse
Os usuários não são sincronizados
Verifique estes pontos:
- Há um Segredo do hook salvo no painel Hook antes de criar usuário no Notifuse?
- A chave de assinatura do webhook está correta no Supabase e no Notifuse?
- Procure mensagens de erro nos logs do Notifuse
- Lembre-se: os erros no Before User Created Hook são registrados no log, mas não impedem cadastros
Erros de assinatura inválida
Isso geralmente significa que:
- A chave de assinatura no Notifuse não corresponde à do Supabase
- A URL do webhook tem os parâmetros
workspace_idouintegration_iderrados - Você está testando com uma ferramenta como o Postman sem o cabeçalho de assinatura correto
Para corrigir:
- Gere a chave de assinatura de novo no Supabase
- Copie a nova chave para o Notifuse
- Use exatamente a URL de webhook fornecida pelo Notifuse
Comportamento da troca de email
O fluxo de “secure email change” do Supabase envia dois emails:
- Para o endereço de email atual: usa
template_mappings.email_change_current- Variáveis disponíveis:
user.email,user.email_new,email_data.token_hash_new - URL de confirmação:
{{ email_data.site_url }}/verify?token={{ email_data.token_hash_new }}&type=email_change&redirect_to={{ email_data.redirect_to }}
- Variáveis disponíveis:
- Para o novo endereço de email: usa
template_mappings.email_change_new- Variáveis disponíveis:
user.email,user.email_new,email_data.token_hash - URL de confirmação:
{{ email_data.site_url }}/verify?token={{ email_data.token_hash }}&type=email_change&redirect_to={{ email_data.redirect_to }}
- Variáveis disponíveis:
Por compatibilidade com versões anteriores, os nomes dos tokens do Supabase são contraintuitivos:
token_hash_newé usado para o endereço de email atualtoken_hashé usado para o novo endereço de email
A troca só é concluída depois que os dois emails são confirmados. O Notifuse detecta as trocas seguras de email e envia a cada endereço o token certo.
Configuração avançada
Lógica personalizada de lista de contatos
Para escolher a lista com outras regras (os metadados do usuário, por exemplo):
- Deixe a lista de destino vazia nas configurações da integração
- Use segmentos do Notifuse para agrupar os usuários
- Crie uma automação disparada quando novos contatos forem adicionados
Personalização dos emails
Você pode editar qualquer template gerenciado pela integração:
- Personalize cores, fontes e layout
- Adicione o seu logo e os elementos da sua marca
- Mude o texto, mantendo as variáveis de template
- Adicione parâmetros UTM para rastreamento
Os templates gerenciados pela integração não podem ser excluídos, mas tudo neles pode ser alterado.
Limitações
- Os templates gerenciados pela integração não podem ser excluídos (podem ser editados)
- Cada projeto do Supabase precisa da sua própria integração no Notifuse
- O Before User Created Hook só dispara para novos cadastros de usuários (não para usuários existentes)
- As variáveis de template são definidas pelo Supabase e não podem ser modificadas
Boas práticas
- Configure a integração em um workspace de desenvolvimento antes de colocá-la em produção.
- Trate os templates padrão como ponto de partida e adapte-os à sua marca.
- Confira os logs do Notifuse com regularidade para garantir que os webhooks são processados.
- Agrupe os usuários com segmentos em vez de listas estáticas.
- Trate as chaves de assinatura dos webhooks como senhas e nunca as inclua no controle de versão.
