> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Supabase

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

![Integrazione Supabase](https://www.notifuse.com/docs/assets/integrations/supabase.png)

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](https://supabase.com/dashboard/project/_/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](https://www.notifuse.com/docs/assets/screenshots/supabase/supabase_settings.png)

![Configurazione dell'Auth Hook di Supabase](https://www.notifuse.com/docs/assets/screenshots/supabase/supabase_hook.png)

![Integrazione Notifuse](https://www.notifuse.com/docs/assets/screenshots/supabase/supabase_notifuse.png)

![Endpoint di Notifuse](https://www.notifuse.com/docs/assets/screenshots/supabase/supabase_endpoints.png)

### 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](https://www.notifuse.com/docs/assets/screenshots/supabase/supabase_templates.png)

### Variabili dei template

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

```liquid
{# 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:

```liquid
{{ 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
<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 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

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.

## Documentazione correlata

- [Supabase Auth Hooks: Send Email Hook](https://supabase.com/docs/guides/auth/auth-hooks/send-email-hook)
- [Supabase Auth Hooks: Before User Created Hook](https://supabase.com/docs/guides/auth/auth-hooks/before-user-created-hook)
- [Template email di Notifuse](https://www.notifuse.com/it/docs/features/templates.md)
- [Contatti di Notifuse](https://www.notifuse.com/it/docs/features/contacts.md)
- [Liste di Notifuse](https://www.notifuse.com/it/docs/features/lists.md)
