I webhook permettono a Loyaltify di avvisare subito i tuoi altri sistemi quando succede qualcosa, ad esempio quando si iscrive un nuovo cliente o un cliente guadagna punti. Loyaltify invia un breve messaggio a un indirizzo che scegli tu, e il tuo sistema può agire di conseguenza.

Sono utili per tenere aggiornato un CRM, attivare email nei tuoi strumenti o creare report. Questa guida spiega come configurarne uno, cosa contiene ogni messaggio e come verificare che i messaggi arrivino.

💡 Buono a sapersi: questa funzione fa parte del piano Advanced. Smette di funzionare se passi a un piano inferiore.

Configura un webhook

Passo 1: apri la configurazione del webhook

Vai su Integrazioni e clicca su Connetti nel riquadro Webhook.

Passo 2: compila i dati

Nella finestra Configurazione del webhook:

URL dell'endpoint: l’indirizzo https del tuo sistema che deve ricevere i messaggi.
Autorizzazione: scegli Bearer e digita un token a tua scelta, oppure scegli Nessuna.
Eventi: spunta quelli che ti interessano. Ne serve almeno uno.

Poi salva, e il tuo webhook è attivo.

💡 Consiglio: scegli Bearer e un token lungo e casuale. Così ogni messaggio include l’header Authorization: Bearer seguito dal tuo token, e il tuo sistema può verificare che il messaggio arrivi davvero da Loyaltify. Questo token è diverso dalla tua chiave API.

Modificalo in seguito

Puoi modificare l’endpoint, l’autorizzazione e gli eventi in qualsiasi momento nella pagina Configurazione webhook. Clicca su Salva quando hai finito.

Gli eventi che puoi scegliere

Cliente creato (customer.created): si iscrive un nuovo cliente.
Cliente aggiornato (customer.updated): i dati di un cliente vengono modificati.
Transazione creata (transaction.created): un cliente riceve il saldo iniziale, guadagna, riscatta, riceve un premio referral o gli scadono dei punti.
Tentativo di registrazione di un cliente esistente (customer.signup_attempt): una persona che ha già la carta compila di nuovo il tuo modulo. I suoi dati salvati non vengono modificati dal nuovo invio.

Cosa contiene ogni messaggio

Loyaltify invia ogni messaggio in formato JSON, con gli header Content-Type: application/json e User-Agent: Loyaltify-Webhook/1.0. Ogni messaggio è composto da tre parti:

event: di quale evento si tratta, ad esempio customer.created.
timestamp: quando è successo, in UTC (ad esempio 2026-10-16T16:38:46Z).
data: i dettagli, che dipendono dall’evento.

I numeri come point e balance_after vengono inviati come testo, ad esempio "1.0", e i valori vuoti sono null.

Cliente creato e Cliente aggiornato

name, email, phone e birthday
uuid: l’ID del cliente (lo stesso che si trova nel codice QR della sua carta)
point: il suo saldo (in Cliente creato, il saldo iniziale)
custom_fields: le risposte alle tue domande personalizzate, compresi i valori nascosti del link del modulo, come click_id
is_marketing_opted_in: se ha dato il consenso marketing
created_at, updated_at e store_uuid

Cliente aggiornato contiene gli stessi campi, con i nuovi valori. Ecco un esempio di Cliente creato:

{
  "data": {
    "name": "Alex",
    "uuid": "7f3e9a21",
    "email": "[email protected]",
    "phone": null,
    "point": "1.0",
    "birthday": null,
    "created_at": "2026-10-16T16:38:41.704Z",
    "store_uuid": "a1b2c3d4",
    "updated_at": "2026-10-16T16:38:46.790Z",
    "custom_fields": {},
    "is_marketing_opted_in": true
  },
  "event": "customer.created",
  "timestamp": "2026-10-16T16:38:46Z"
}

Transazione creata

kind: il tipo di transazione, ad esempio initial (il saldo iniziale all’iscrizione), manual, redeem, expired, referee o referrer
point e amount: i valori della transazione. Nelle scadenze, point è negativo.
balance_after: il saldo del cliente dopo la transazione
campaign: nei riscatti, la campagna riscattata
user: il membro del team che ha scansionato (nome, ID ed email), oppure null per gli eventi automatici come le scadenze
customer_uuid, customer_email e customer_phone
referred_by_uuid: nei premi referral, chi ha invitato il cliente
uuid: l’ID della transazione stessa
created_at e store_uuid

Ecco un esempio di un membro del team che aggiunge un punto:

{
  "data": {
    "kind": "manual",
    "user": {
      "name": "Sam Taylor",
      "uuid": "0b8e7d4c-1f2a-4c3b-9d5e-6a7b8c9d0e1f",
      "email": "[email protected]"
    },
    "uuid": "5c9d2e7a-3b4f-4a1c-8e6d-2f7a9b0c1d3e",
    "point": "1.0",
    "amount": null,
    "campaign": null,
    "created_at": "2026-10-16T16:45:10.375Z",
    "store_uuid": "a1b2c3d4",
    "balance_after": "2.0",
    "customer_uuid": "7f3e9a21",
    "customer_email": "[email protected]",
    "customer_phone": null,
    "referred_by_uuid": null
  },
  "event": "transaction.created",
  "timestamp": "2026-10-16T16:45:10Z"
}

Un premio referral invia due transazioni nello stesso momento: referee per il nuovo cliente, con referred_by_uuid impostato sull’ID del segnalante, e referrer per il cliente che lo ha invitato.

Tentativo di registrazione di un cliente esistente

customer: chi è il cliente esistente, con il suo uuid e i suoi custom_fields
matched_on: come è stato riconosciuto, ad esempio tramite l’email
submission: cosa ha appena inserito nel modulo
form: quale modulo ha usato

Per vedere un messaggio completo, apri un qualsiasi invio in Eventi recenti (vedi sotto).

Controlla gli invii

La pagina Configurazione webhook elenca i tuoi Eventi recenti con stato, codice di risposta, numero di tentativi e data. Clicca sull’icona dell’occhio per vedere esattamente cosa è stato inviato, gli header e la risposta del tuo sistema.

I messaggi non arrivano?

Verifica che l’URL dell'endpoint sia un indirizzo https valido. A volte i browser inseriscono automaticamente un indirizzo email in quel campo.
Verifica che l’evento sia spuntato nella pagina Configurazione webhook.
Verifica di avere il piano Advanced.
Controlla l’evento in Eventi recenti. Se il codice di risposta indica un errore, il tuo sistema ha ricevuto il messaggio ma lo ha rifiutato, e l’icona dell’occhio mostra la sua risposta.

Il problema persiste? Contatta l’assistenza tramite la chat dal vivo.

Buono a sapersi

I messaggi potrebbero non arrivare in ordine, quindi usa il timestamp se l’ordine è importante.
Prepara il tuo sistema a gestire lo stesso evento due volte, per sicurezza. Per le transazioni, l’uuid in data è univoco per ciascuna.
Lavori con l’API? I webhook inviano l’ID breve del cliente. Alcune richieste API richiedono invece il numero interno del cliente, e la documentazione dell’API spiega come risalire dall’uno all’altro.
Usi Omnisend? La guida di Omnisend usa un webhook per collegarsi a Loyaltify. Trovi il link nella Panoramica delle integrazioni.

Hai bisogno di aiuto?

Siamo qui per aiutarti!

Se hai domande sui webhook, scrivici tramite la chat dal vivo all’interno di Loyaltify, oppure usa il pulsante della chat in basso a destra in questa pagina. Il nostro team sarà felice di aiutarti.

Webhooks