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:
- Auth Email Hook: invia le email transazionali per gli eventi di autenticazione (registrazione, magic link, recupero password e così via)
- 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
- Vai in Supabase Auth Hooks nella tua Supabase Dashboard e apri le impostazioni dell’Auth Email Hook
- Aggiungi un nuovo hook
- Seleziona il tipo “HTTPS”
- Clicca “Generate a secret” e copia il valore nell’integrazione Notifuse
- Salva l’integrazione per vedere l’endpoint webhook generato da Notifuse
- Incolla l’endpoint webhook nel tuo hook Supabase e salva
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
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
- Apri il pannello Hook prima della creazione utente nel modulo dell’integrazione Supabase
- Genera in Supabase una chiave segreta per il webhook (diversa da quella dell’Auth Email Hook)
- Incolla la chiave segreta nel modulo dell’integrazione Supabase in Notifuse
- (Facoltativo) Seleziona una lista di contatti a cui aggiungere i nuovi utenti
- (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 Supabase | Campo Notifuse |
|---|---|
email | email |
id | external_id |
phone | phone |
user_metadata | Campo 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
- Nella tua applicazione, avvia un flusso di autenticazione (per esempio una registrazione)
- Controlla i log di Notifuse per verificare che il webhook sia stato ricevuto
- Controlla che l’email sia arrivata nella casella del destinatario
Testare la sincronizzazione degli utenti
- Crea un nuovo utente nel tuo progetto Supabase
- In Notifuse, vai in Contatti
- Cerca l’email dell’utente per verificare che sia stato aggiunto
- 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_idointegration_idsbagliati - 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:
- 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 }}
- Variabili disponibili:
- 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 }}
- Variabili disponibili:
Per retrocompatibilità, i nomi dei token di Supabase sono controintuitivi:
token_hash_newsi usa per l’indirizzo email attualetoken_hashsi 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):
- Lascia vuota la lista di destinazione nelle impostazioni dell’integrazione
- Usa i segmenti di Notifuse per raggruppare gli utenti
- 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
- Configura l’integrazione in un workspace di sviluppo prima di andare in produzione.
- Considera i template predefiniti un punto di partenza e adattali al tuo brand.
- Controlla regolarmente i log di Notifuse per verificare che i webhook vengano elaborati.
- Raggruppa gli utenti con i segmenti invece che con liste statiche.
- Tratta le chiavi di firma dei webhook come password e non inserirle mai nel controllo di versione.
