Vai al contenuto

Integrazioni

Supabase

Integra Supabase Auth con Notifuse per le email di autenticazione e la sincronizzazione degli utenti.

Integrazione Supabase

L’integrazione Supabase invia le email di Supabase Auth tramite Notifuse e sincronizza i nuovi utenti con i tuoi contatti.

Panoramica

È composta da due parti:

  1. Auth Email Hook: invia le email transazionali per gli eventi di autenticazione (registrazione, magic link, recupero password e così via)
  2. Before User Created Hook: aggiunge i nuovi utenti Supabase ai tuoi contatti Notifuse

Configurazione

Vai in Impostazioni → Integrazioni, clicca Aggiungi integrazione, poi scegli Supabase sotto App collegate.

Prerequisiti

Ti servono:

  • Un workspace Notifuse con i permessi necessari
  • Un progetto Supabase
  • Almeno un’integrazione email configurata in Notifuse (per inviare le email transazionali)

Auth Email Hook

L’Auth Email Hook invia tramite Notifuse le tue email di autenticazione al posto di quelle predefinite di Supabase.

Attivazione

  1. Vai in Supabase Auth Hooks nella tua Supabase Dashboard e apri le impostazioni dell’Auth Email Hook
  2. Aggiungi un nuovo hook
  3. Seleziona il tipo “HTTPS”
  4. Clicca “Generate a secret” e copia il valore nell’integrazione Notifuse
  5. Salva l’integrazione per vedere l’endpoint webhook generato da Notifuse
  6. Incolla l’endpoint webhook nel tuo hook Supabase e salva
Supabase Auth Hooks Configurazione dell'Auth Hook di Supabase Integrazione Notifuse Endpoint di Notifuse

Template predefiniti

Al primo salvataggio dell’integrazione Supabase, Notifuse crea un template predefinito per ogni tipo di email. Questi template:

  • Sono indicati come gestiti dall’integrazione (non si possono eliminare)
  • Includono tutte le variabili Liquid di Supabase necessarie
  • Si possono modificare per adattarli al tuo brand
Template Notifuse per Supabase

Variabili dei template

Tutti i template delle email di autenticazione Supabase hanno accesso a queste variabili:

{# 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 dell’URL di conferma

I link di conferma devono usare esattamente questo formato per funzionare con il sistema di autenticazione GoTrue di Supabase:

{{ email_data.site_url }}/verify?token={{ email_data.token_hash }}&type={{ email_data.email_action_type }}&redirect_to={{ email_data.redirect_to }}

Si ottiene un URL come questo:

https://yourproject.supabase.co/auth/v1/verify?token=abc123...&type=signup&redirect_to=https://yourapp.com

Nell’URL usa token_hash, non token. La variabile token serve a mostrare i codici OTP nelle email di riautenticazione.

Template di esempio

Un template di conferma della registrazione con il formato di URL corretto:

<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

Il Before User Created Hook aggiunge i nuovi utenti Supabase ai tuoi contatti Notifuse.

Attivazione

  1. Apri il pannello Hook prima della creazione utente nel modulo dell’integrazione Supabase
  2. Genera in Supabase una chiave segreta per il webhook (diversa da quella dell’Auth Email Hook)
  3. Incolla la chiave segreta nel modulo dell’integrazione Supabase in Notifuse
  4. (Facoltativo) Seleziona una lista di contatti a cui aggiungere i nuovi utenti
  5. (Facoltativo) Rifiuta gli indirizzi email usa e getta (per esempio @yopmail.com)

Corrispondenza dei campi

I campi utente di Supabase corrispondono a questi campi contatto di Notifuse:

Campo SupabaseCampo Notifuse
emailemail
idexternal_id
phonephone
user_metadataCampo Custom JSON configurabile (facoltativo)

Nelle impostazioni dell’integrazione puoi scegliere quale campo Custom JSON (da 1 a 5) riceve lo user_metadata di Supabase. Se non ne selezioni nessuno, user_metadata non viene sincronizzato.

Gestione degli errori

Il Before User Created Hook non blocca mai una registrazione nella tua applicazione. L’errore viene registrato nei log e la registrazione prosegue quando:

  • L’upsert del contatto fallisce
  • La lista di contatti configurata è stata eliminata

Sicurezza

Verifica della firma dei webhook

Notifuse verifica ogni webhook di Supabase tramite la sua firma HMAC-SHA256 e rifiuta quelli con una firma non valida, quindi elabora solo le richieste provenienti dal tuo progetto Supabase.

Crittografia

Le chiavi di firma dei webhook sono cifrate a riposo nel database di Notifuse con crittografia AES-256.

Test

Testare le email di autenticazione

  1. Nella tua applicazione, avvia un flusso di autenticazione (per esempio una registrazione)
  2. Controlla i log di Notifuse per verificare che il webhook sia stato ricevuto
  3. Controlla che l’email sia arrivata nella casella del destinatario

Testare la sincronizzazione degli utenti

  1. Crea un nuovo utente nel tuo progetto Supabase
  2. In Notifuse, vai in Contatti
  3. Cerca l’email dell’utente per verificare che sia stato aggiunto
  4. Se hai configurato una lista di destinazione, controlla che l’utente ci sia

Risoluzione dei problemi

Le email non vengono inviate

Controlla questi punti:

  • Hai salvato un Segreto hook nel pannello Hook di invio email in Notifuse?
  • La chiave di firma del webhook è corretta sia in Supabase sia in Notifuse?
  • Hai un provider email transazionale configurato nel tuo workspace?
  • Cerca messaggi di errore nei log di Notifuse

Gli utenti non vengono sincronizzati

Controlla questi punti:

  • Hai salvato un Segreto hook nel pannello Hook prima della creazione utente in Notifuse?
  • La chiave di firma del webhook è corretta sia in Supabase sia in Notifuse?
  • Cerca messaggi di errore nei log di Notifuse
  • Ricorda: gli errori del Before User Created Hook vengono registrati nei log ma non impediscono le registrazioni

Errori di firma non valida

Di solito significa che:

  • La chiave di firma in Notifuse non corrisponde a quella in Supabase
  • L’URL del webhook contiene parametri workspace_id o integration_id sbagliati
  • Stai testando con uno strumento come Postman senza l’header di firma corretto

Per risolvere:

  • Rigenera la chiave di firma in Supabase
  • Copia la nuova chiave in Notifuse
  • Assicurati di usare esattamente l’URL del webhook fornito da Notifuse

Comportamento del cambio email

Il flusso “secure email change” di Supabase invia due email:

  1. All’indirizzo email attuale: usa template_mappings.email_change_current
    • Variabili disponibili: user.email, user.email_new, email_data.token_hash_new
    • URL di conferma: {{ email_data.site_url }}/verify?token={{ email_data.token_hash_new }}&type=email_change&redirect_to={{ email_data.redirect_to }}
  2. Al nuovo indirizzo email: usa template_mappings.email_change_new
    • Variabili disponibili: user.email, user.email_new, email_data.token_hash
    • URL di conferma: {{ email_data.site_url }}/verify?token={{ email_data.token_hash }}&type=email_change&redirect_to={{ email_data.redirect_to }}

Per retrocompatibilità, i nomi dei token di Supabase sono controintuitivi:

  • token_hash_new si usa per l’indirizzo email attuale
  • token_hash si usa per il nuovo indirizzo email

Il cambio si completa solo quando entrambe le email sono state confermate. Notifuse riconosce i cambi email sicuri e invia a ogni indirizzo il token giusto.

Configurazione avanzata

Logica personalizzata per la lista dei contatti

Per scegliere la lista in base ad altre regole (per esempio i metadati utente):

  1. Lascia vuota la lista di destinazione nelle impostazioni dell’integrazione
  2. Usa i segmenti di Notifuse per raggruppare gli utenti
  3. Crea un’automazione che si attiva quando vengono aggiunti nuovi contatti

Personalizzazione delle email

Puoi modificare qualsiasi template gestito dall’integrazione:

  • Personalizza colori, font e layout
  • Aggiungi il tuo logo e gli elementi del tuo brand
  • Cambia i testi, mantenendo le variabili del template
  • Aggiungi parametri UTM per il tracciamento

I template gestiti dall’integrazione non si possono eliminare, ma tutto il loro contenuto si può modificare.

Limitazioni

  • I template gestiti dall’integrazione non si possono eliminare (si possono modificare)
  • Ogni progetto Supabase richiede una propria integrazione in Notifuse
  • Il Before User Created Hook si attiva solo per le registrazioni di nuovi utenti (non per gli utenti esistenti)
  • Le variabili dei template sono stabilite da Supabase e non si possono modificare

Buone pratiche

  1. Configura l’integrazione in un workspace di sviluppo prima di andare in produzione.
  2. Considera i template predefiniti un punto di partenza e adattali al tuo brand.
  3. Controlla regolarmente i log di Notifuse per verificare che i webhook vengano elaborati.
  4. Raggruppa gli utenti con i segmenti invece che con liste statiche.
  5. Tratta le chiavi di firma dei webhook come password e non inserirle mai nel controllo di versione.