Configurare le integrazioni in Drimify (webhook e mailer)

Le integrazioni di Drimify consentono di inviare automaticamente i dati dei partecipanti a servizi esterni ogni volta che un utente interagisce con la tua applicazione. Puoi collegare un'API personalizzata, HubSpot o Salesforce e specificare esattamente quali campi trasmettere per ogni integrazione.

Per iniziare

Se non hai ancora configurato nessuna integrazione, vedrai la schermata con il messaggio "Nessuna integrazione webhook" o "Nessuna integrazione mailer".
Fai clic su + Aggiungi nuova integrazione (disponibile sia in alto a destra sia al centro della pagina) per aprire il selettore delle integrazioni.

Integrazioni webhook

Selezionare il tipo di integrazione

Si aprirà una finestra modale intitolata "Seleziona integrazione webhook".
Puoi filtrare per categoria tramite il menu a discesa (l'opzione predefinita è Tutte). Le tre integrazioni disponibili sono:

• API personalizzata — per qualsiasi endpoint API REST che gestisci
• HubSpot — per il CRM e l'automazione del marketing tramite HubSpot
• Salesforce — per il CRM Salesforce

Fai clic sul riquadro dell'integrazione che vuoi configurare.

Integrazione API personalizzata

Autenticazione

Dopo aver selezionato API personalizzata, si apre il pannello Aggiungi integrazione con i seguenti campi:

• Nome integrazione: un'etichetta per identificare l'integrazione (valore predefinito: "Integrazione API personalizzata"). Puoi sostituirla con un nome più descrittivo.
• Endpoint API: l'URL completo del servizio che riceve il webhook (ad esempio: https://api.example.com/webhook). Deve essere un endpoint HTTPS.
• Metodo HTTP:

Seleziona il metodo HTTP da usare per inviare la richiesta webhook al tuo endpoint.
Le opzioni disponibili sono:

• POST — consigliato per la maggior parte dei casi d'uso (crea una nuova risorsa o invia dati)
• PUT — sostituisce completamente una risorsa esistente
• PATCH — aggiorna parzialmente una risorsa esistente

Scegli il metodo previsto dalla tua API per ricevere i dati.

• Tipo di autenticazione: scegli il metodo di autenticazione utilizzato dal tuo endpoint.

• Quando selezioni Autenticazione di base, vengono visualizzati due campi: Login (nome utente) e Password. Inserisci le credenziali così come sono: Drimify genera automaticamente l'header Authorization: Basic. Non devi codificarle manualmente.
• Quando selezioni Header personalizzato, viene visualizzato il campo aggiuntivo Nome header personalizzato, in cui puoi inserire il nome della chiave dell'header.
• Chiave API: il valore segreto inviato tramite il metodo di autenticazione selezionato.
• Verifica la connessione: fai clic su questo pulsante prima di salvare per verificare che Drimify riesca a raggiungere il tuo endpoint con le credenziali fornite.

Recuperare il token da un endpoint di autenticazione (chiamata preliminare)

Alcune API richiedono un'autenticazione preliminare: devi chiamare un endpoint di autenticazione con le tue credenziali, ricevere un token e utilizzarlo nella chiamata webhook vera e propria. Drimify gestisce automaticamente questa procedura.

Quando il tipo di autenticazione è Chiave API, Bearer Token o Header personalizzato, viene visualizzata la casella di controllo "Recupera questo token da un endpoint di autenticazione". Se la selezioni, il campo delle credenziali statiche viene sostituito dalle impostazioni della chiamata preliminare descritte di seguito. Per l'header personalizzato, il campo del nome dell'header rimane visibile: il token recuperato viene inviato in quell'header.

Il token recuperato viene inserito in base al tipo di autenticazione:

• Bearer Token → Authorization: Bearer <token>
• Chiave API → X-API-KEY: <token>
• Header personalizzato → <your header name>: <token>

Scegli uno dei tre metodi

OAuth2 (client_credentials) — per i server OAuth2 standard (ad es. Keycloak).

• Campi: URL del token, Client ID, Client Secret, Scope (facoltativo)
• Drimify invia una richiesta OAuth2 client_credentials standard e legge il token da access_token. La durata del token viene ricavata dal valore expires_in restituito dal server.

Login JSON — per gli endpoint di login che accettano un corpo JSON e restituiscono un token.

• Campi: URL di autenticazione, Corpo (elenco di coppie chiave/valore), Percorso del token
• Drimify invia una richiesta POST con un corpo JSON generato dalle coppie chiave/valore inserite (ad es. le righe email = a@b.com e password = secret producono {"email":"a@b.com","password":"secret"}).
• Percorso del token indica a Drimify dove si trova il token nella risposta JSON, usando la notazione con punti: ad es. data.access_token, oppure semplicemente token se si trova al livello principale.

Personalizzato — per i casi non coperti dai due metodi precedenti.

• Campi: URL di autenticazione, Metodo HTTP (POST o GET), Header (elenco di coppie chiave/valore), Corpo (elenco di coppie chiave/valore), Codifica del corpo (JSON o form-urlencoded), Percorso del token
• Con il metodo GET, la richiesta non ha un corpo: passa i parametri tramite gli header o l'URL di autenticazione.
• Se aggiungi manualmente un header Content-Type, questo ha la precedenza su quello previsto dalla codifica del corpo.

Elenchi di coppie chiave/valore (corpo e header)

Ogni riga contiene una chiave, un valore e una casella di controllo "Sensibile" (selezionata per impostazione predefinita). Puoi aggiungere e rimuovere le righe, ma non modificarle direttamente: per modificare una riga, rimuovila e aggiungila di nuovo. Puoi indicare che un valore è sensibile solo quando aggiungi la riga. Dopo il salvataggio, i valori sensibili vengono mascherati e non sono più visibili, né nel modulo né nei log.

Memorizzazione dei token nella cache e nuovi tentativi

• I token OAuth2 vengono memorizzati nella cache per la durata indicata da expires_in.
• Per Login JSON e Personalizzato, imposta Validità del token (minuti): se lasci il campo vuoto, il valore predefinito è 60 minuti.
• I token vengono conservati nella cache per un massimo di 7 giorni.
• Se il tuo endpoint restituisce 401 mentre è in uso un token memorizzato nella cache, Drimify elimina il token, esegue nuovamente l'autenticazione e riprova la chiamata una sola volta.
• Se la chiamata preliminare non riesce (errore, timeout o nessun token trovato nel percorso indicato), il webhook non viene inviato senza autenticazione: l'invio non riuscito viene registrato nei log e la coda di invio effettua un nuovo tentativo secondo la procedura abituale.

Verificare la connessione con una chiamata preliminare

Il pulsante Verifica la connessione supporta pienamente la chiamata preliminare: prima esegue l'autenticazione presso il tuo endpoint, poi effettua la chiamata di prova con il token recuperato.

Integrazione HubSpot

Dopo aver selezionato HubSpot, il pannello mostra:

• Nome integrazione: valore predefinito: "Integrazione HubSpot".
• Chiave API / Token di accesso: incolla qui il token di accesso della tua app privata HubSpot. HubSpot ha deprecato le vecchie chiavi API nel 2022, quindi devi utilizzare un token di un'app privata generato nel tuo account HubSpot in: Impostazioni → Integrazioni → App private
• Verifica la connessione: verifica il token tramite l'API HubSpot prima del salvataggio.

Integrazione Salesforce

Dopo aver selezionato Salesforce, il pannello mostra:

• Nome integrazione: valore predefinito: "Integrazione Salesforce".
• Dominio Salesforce: l'URL della tua istanza Salesforce (ad esempio: yourcompany.my.salesforce.com).
• Consumer Key e Consumer Secret: si ottengono da un'app connessa configurata in Salesforce in: Configurazione → Gestore delle applicazioni → Nuova app connessa. Drimify utilizza il flusso OAuth 2.0 Client Credentials.
• Nome del campo ID esterno: il nome API del campo utilizzato per individuare i record da creare o aggiornare (upsert), in genere Email_External_Id__c o un altro campo ID esterno personalizzato sull'oggetto Contatto. Questo campo deve essere contrassegnato come ID esterno in Salesforce. Drimify crea o aggiorna i Contatti. I lead non sono ancora supportati.
• Origine dell'ID esterno: un menu a discesa che consente di selezionare il campo dati di Drimify da utilizzare come chiave di corrispondenza (ad esempio: Email).
• Verifica la connessione: verifica la connessione OAuth a Salesforce prima del salvataggio.

⚠️ Campi obbligatori in Salesforce

Salesforce prevede alcuni campi obbligatori per l'oggetto Contatto. Per creare un contatto, Salesforce richiede almeno:

• lastName

Sebbene Email non sia obbligatorio nello schema predefinito di Salesforce, è quasi sempre necessario come ID esterno per individuare correttamente i record ed evitare duplicati durante le operazioni di upsert. Senza una corrispondenza affidabile tramite ID esterno, Salesforce potrebbe creare record duplicati o restituire un errore.

Buone pratiche

Quando configuri il collegamento a Salesforce, associa sempre almeno:

• Cognome
• Email

Se ometti Cognome, l'invio del webhook non riuscirà e il record non verrà creato né aggiornato.

Associazione dei campi

Disponibile per tutti e tre i tipi di integrazione, la funzione Associa campi consente di specificare esattamente quali campi dati di Drimify inviare all'integrazione e quali nomi assegnare alle relative chiavi.
Fai clic su + Aggiungi campo per aggiungere una riga di associazione.

Ogni riga è composta da:

• Campo webhook (a sinistra) — il nome della chiave che comparirà nel payload in uscita, definito da te in base ai requisiti dell'integrazione
• → Campo di origine (menu a discesa a destra) — il valore di origine per questo campo. Puoi:
• • Selezionare un campo dati di Drimify (ad es. Riferimento App, Email, Punteggio) per inviare un valore dinamico raccolto dal partecipante
  • Selezionare Valore statico per inviare un valore fisso preimpostato ogni volta che viene attivato il webhook. Verrà visualizzato un campo di testo aggiuntivo in cui inserire il valore (ad es. My_Value). È utile per trasmettere costanti come il nome di un evento, un identificatore di origine o un tag di ambiente.

Campi di origine disponibili in Drimify

Puoi aggiungere tutte le associazioni necessarie.
Per rimuovere un'associazione, fai clic sull'icona del cestino a destra della riga.## Indicare nel CRM che un contatto proviene da Drimify

Drimify non imposta automaticamente una sorgente, ma puoi farlo tramite la mappatura dei campi, sia in Salesforce sia in HubSpot:

1. Nel CRM, crea un campo in cui memorizzare la sorgente. In Salesforce, crea un campo di testo nell'oggetto Contatti (ad esempio Drimify_Source__c). In HubSpot, crea una proprietà dei contatti (ad esempio drimify_source).
2. Nell'integrazione Drimify, apri Mappa campi e aggiungi una riga inserendo a sinistra il nome API del campo. A destra, scegli Valore statico e inserisci Drimify.
3. Per sapere a quale esperienza ha partecipato il contatto, aggiungi una seconda riga che associ un altro campo (ad esempio Drimify_Game__c) a Riferimento app.

Disponibile nelle aree di lavoro

In fondo al modulo di configurazione dell'integrazione, la sezione Disponibile nelle aree di lavoro ti consente di scegliere quali aree di lavoro possono utilizzare l'integrazione, tramite l'interruttore accanto a ciascuna di esse.
Fai clic su Seleziona tutto per abilitare l'integrazione in tutte le aree di lavoro contemporaneamente.

Salvare e gestire le integrazioni

Una volta compilati tutti i campi, fai clic su Salva modifiche per creare l'integrazione. L'integrazione comparirà nell'elenco principale delle integrazioni. Da questo elenco puoi modificare o eliminare le integrazioni esistenti in qualsiasi momento. Fai clic su Annulla per annullare le modifiche non salvate.

Integrazioni per l'invio di email

Le integrazioni per l'invio di email ti consentono di inviare email transazionali (ad esempio conferme, risultati o messaggi di follow-up) direttamente dalle tue esperienze Drimify, utilizzando il provider di posta elettronica che preferisci.

Aggiungere un'integrazione per l'invio di email

1. Vai su Integrazioni → Integrazioni per l'invio di email
2. Fai clic su Aggiungi integrazione per l'invio di email
3. Seleziona il provider:

• Amazon SES
• Brevo
• Drimify
• Mailgun
• Mailjet
• Mandrill
• SendGrid
• Tipimail
• SMTP personalizzato

Configurare l'integrazione per l'invio di email

Impostazioni generali

Tutti i provider prevedono le seguenti impostazioni generali:

• Nome dell'integrazione – Nome interno per identificare l'integrazione
• Nome del mittente – Nome visualizzato come mittente delle email
• Email del mittente – Indirizzo email utilizzato per inviare le email (non applicabile a Drimify: vedi sotto)
• Email in CCN (facoltativo) – Indirizzo email a cui inviare una copia di tutte le email in uscita

Autenticazione

Ogni provider richiede credenziali specifiche. Per i dettagli, consulta la sezione dedicata alla configurazione del provider qui sotto.

Verificare la connessione

Dopo aver inserito le credenziali, fai clic su Invia email di prova per verificare che l'integrazione funzioni correttamente. Se la connessione funziona, comparirà il messaggio di conferma Email di prova inviata correttamente.

Campi dei parametri del modello

Associa i campi dati di Drimify alle variabili del modello del tuo provider di posta elettronica. Questa sezione è disponibile per i provider che supportano modelli di email dinamici: Brevo, Mailgun, Mailjet, Mandrill, SendGrid e Tipimail.

• Nome del parametro – Nome della variabile previsto nel modello di email
• Campo – Dato corrispondente in Drimify (ad esempio Nome, Email, Punteggio, ecc.)

Fai clic su Aggiungi campo per creare altre associazioni.

Disponibile nelle aree di lavoro

Seleziona le aree di lavoro che possono utilizzare questa integrazione per l'invio di email.

Configurazione dei singoli provider

Amazon SES

Cosa ti serve:

• Un utente AWS IAM con l'autorizzazione ses:SendEmail
• Una chiave di accesso API e una chiave privata API (da AWS IAM)
• La tua regione AWS (ad esempio eu-west-1, us-east-1)
• Un token di sessione (solo se utilizzi credenziali temporanee/STS)
• Un indirizzo email del mittente o un dominio verificato in Amazon SES

Procedura:

1. In AWS IAM, crea un utente con le autorizzazioni di invio SES e genera una coppia di chiavi di accesso
2. In Drimify, inserisci Chiave di accesso API, Chiave privata API e Regione
3. Se utilizzi credenziali temporanee, inserisci anche il Token di sessione
4. Assicurati che l'indirizzo email del mittente o il dominio sia verificato in Amazon SES
5. Fai clic su Invia email di prova per verificare la connessione
6. Salva l'integrazione

Brevo

Cosa ti serve:

• Una chiave API di Brevo

Procedura:

1. Nel tuo account Brevo, genera una chiave API in Impostazioni → Chiavi API
2. Incollala nel campo Chiave API in Drimify
3. Fai clic su Invia email di prova per verificare la connessione
4. Salva l'integrazione

Drimify

Non è richiesta alcuna autenticazione. Le email vengono inviate tramite l'infrastruttura di posta elettronica interna di Drimify (notification@digitaservice.com).
Cosa ti serve:

• Un nome del mittente
• Un indirizzo email per le risposte (ad esempio contact@yourcompany.com)
• Facoltativamente, un indirizzo email in CCN

Procedura:

1. Seleziona Drimify come provider
2. Inserisci Nome del mittente e Email per le risposte
3. Se lo desideri, aggiungi un'Email in CCN
4. Seleziona le aree di lavoro che devono utilizzare questa integrazione e salva

Mailgun

Cosa ti serve:

• Una chiave API di Mailgun
• Il dominio di invio registrato in Mailgun
• La regione API (US o EU)

Procedura:

1. Nel tuo account Mailgun, recupera la chiave API e il dominio di invio
2. In Drimify, inserisci Chiave API, Dominio API e Regione API
3. Fai clic su Invia email di prova per verificare la connessione
4. Salva l'integrazione

Mailjet

Cosa ti serve:

• Una chiave di accesso API e una chiave privata API di Mailjet

Procedura:

1. Nel tuo account Mailjet, vai su Impostazioni account → REST API → Gestione chiavi API
2. Copia la Chiave di accesso API e la Chiave privata API
3. Inseriscile entrambe in Drimify
4. Fai clic su Invia email di prova per verificare la connessione
5. Salva l'integrazione

Mandrill

Cosa ti serve:

• Una chiave API di Mandrill (Mandrill è un componente aggiuntivo di Mailchimp per l'invio di email transazionali)

Procedura:

1. Nel tuo account Mandrill, vai su Impostazioni → Chiavi API e genera una chiave
2. Incolla la Chiave API in Drimify
3. Fai clic su Invia email di prova per verificare la connessione
4. Salva l'integrazione

SendGrid

Cosa ti serve:

• Una chiave API di SendGrid con le autorizzazioni Mail Send

Procedura:

1. Nel tuo account SendGrid, vai su Impostazioni → Chiavi API e crea una chiave con le autorizzazioni Mail Send
2. Incolla la Chiave API in Drimify
3. Fai clic su Invia email di prova per verificare la connessione
4. Salva l'integrazione

Tipimail

Cosa ti serve:

• Un utente API e una chiave API di Tipimail (Tipimail è il servizio di email transazionali di Sarbacane)

Procedura:

1. Nel tuo account Tipimail, vai su Impostazioni → SMTP e API e recupera Utente API e Chiave API
2. Inseriscili entrambi in Drimify
3. Fai clic su Invia email di prova per verificare la connessione
4. Salva l'integrazione

SMTP personalizzato

Cosa ti serve:

• Il nome host del server SMTP
• La porta SMTP (in genere 587 per TLS, 465 per SSL)
• Il nome utente SMTP (di solito il tuo indirizzo email)
• La password SMTP

Procedura:

1. Recupera le credenziali SMTP dal tuo provider di posta elettronica o dalla configurazione del server
2. In Drimify, inserisci Host, Porta, Nome utente e Password
3. Fai clic su Invia email di prova per verificare la connessione
4. Salva l'integrazione

Aggiornato il: 03/11/2026