Pular para o conteúdo

Integrações

Supabase

Integre o Supabase Auth ao Notifuse para enviar os emails de autenticação e sincronizar os usuários.

Integração com o Supabase

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:

  1. Auth Email Hook: envia os emails transacionais dos eventos de autenticação (cadastro, magic link, recuperação de senha etc.)
  2. 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

  1. Vá em Supabase Auth Hooks no seu Supabase Dashboard e abra as configurações do Auth Email Hook
  2. Adicione um novo hook
  3. Selecione o tipo “HTTPS”
  4. Clique em “Generate a secret” e copie o valor para a integração no Notifuse
  5. Salve a integração para ver o endpoint de webhook gerado pelo Notifuse
  6. Cole o endpoint de webhook no seu hook do Supabase e salve
Auth Hooks do Supabase Configuração de um Auth Hook do Supabase Integração no Notifuse Endpoints do Notifuse

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
Templates do Notifuse para o Supabase

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

  1. Abra o painel Hook antes de criar usuário no formulário da integração com o Supabase
  2. Gere uma chave secreta de webhook no Supabase (diferente da do Auth Email Hook)
  3. Cole a chave secreta no formulário da integração com o Supabase no Notifuse
  4. (Opcional) Selecione uma lista de contatos à qual adicionar os novos usuários
  5. (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 SupabaseCampo do Notifuse
emailemail
idexternal_id
phonephone
user_metadataCampo 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

  1. Na sua aplicação, inicie um fluxo de autenticação (por exemplo, um cadastro)
  2. Confira nos logs do Notifuse se o webhook foi recebido
  3. Confira a caixa de entrada do destinatário

Testar a sincronização de usuários

  1. Crie um novo usuário no seu projeto do Supabase
  2. No Notifuse, vá em Contatos
  3. Procure o email do usuário para confirmar que ele foi adicionado
  4. 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_id ou integration_id errados
  • 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:

  1. 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 }}
  2. 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 }}

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 atual
  • token_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):

  1. Deixe a lista de destino vazia nas configurações da integração
  2. Use segmentos do Notifuse para agrupar os usuários
  3. 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

  1. Configure a integração em um workspace de desenvolvimento antes de colocá-la em produção.
  2. Trate os templates padrão como ponto de partida e adapte-os à sua marca.
  3. Confira os logs do Notifuse com regularidade para garantir que os webhooks são processados.
  4. Agrupe os usuários com segmentos em vez de listas estáticas.
  5. Trate as chaves de assinatura dos webhooks como senhas e nunca as inclua no controle de versão.