Webhook in entrata

📥 Webhook in entrata

Ricevi eventi da piattaforme esterne e assegna semi ai tuoi clienti automaticamente. I webhook in entrata ti permettono di connettere qualsiasi strumento di terze parti — app per quiz, moduli, piattaforme di recensioni, Zapier, Make e altro — al tuo programma di fedeltà LoyaltyTree.

Come Funziona

Il sistema di webhook in entrata utilizza un modello di Fonti & Codici:

1. Crea una Fonte — Una fonte rappresenta una piattaforma o uno strumento esterno (ad es. "Typeform", "Zapier", "La mia app per quiz"). Ogni fonte riceve un URL webhook unico e una chiave segreta per la sicurezza.
2. Aggiungi Codici alla Fonte — Ogni codice definisce un'azione specifica che assegna semi (ad es. "quiz_completato", "modulo_inviato", "richiesta_di_compleanno"). Imposti quanti semi ogni codice assegna, con limiti opzionali.
3. Invia richieste POST — La tua piattaforma esterna invia una richiesta POST all'URL del webhook con il codice e le informazioni del cliente. LoyaltyTree trova o crea il cliente e assegna automaticamente i semi.

Iniziare

Passo 1: Crea una Fonte Webhook

Vai a Negozio → [Il tuo Negozio] → Integrazioni → Webhook in Entrata. Clicca su + Aggiungi Fonte e dai un nome che descriva la piattaforma esterna (ad es. "Quiz Typeform" o "Automazione Zapier").

Quando la fonte è creata, riceverai:

• URL Webhook — L'endpoint a cui la tua piattaforma esterna invierà le richieste
• Segreto Webhook — Una chiave segreta per firmare le richieste (raccomandato per la sicurezza)

Passo 2: Aggiungi Codici

Ogni codice rappresenta un'azione specifica che desideri premiare. Clicca su + Aggiungi Codice sulla tua fonte per crearne uno.

Campo	Richiesto	Descrizione
Codice	Sì	Il valore esatto inviato nel payload del webhook (ad es. quiz_completato). Questo deve corrispondere a ciò che la tua piattaforma esterna invia.
Nome Visualizzato	Sì	Un nome comprensibile mostrato nella dashboard di amministrazione e nella cronologia delle transazioni (ad es. "Quiz Completato").
Descrizione	No	Una nota facoltativa per il tuo team su quando viene utilizzato questo codice.
Quantità di Semi	Sì	Quanti semi assegnare ogni volta che questo codice viene attivato. Predefinito a 1.
Semi Massimi/Cliente	No	Il numero massimo totale di semi che un singolo cliente può guadagnare da questo codice. Lascia vuoto per illimitato. Una volta che un cliente raggiunge questo limite, ulteriori chiamate webhook per loro restituiranno successo ma assegneranno 0 semi.
Cooldown (ore)	No	Ore minime tra le assegnazioni per lo stesso cliente su questo codice. Previene abusi limitando la frequenza con cui un cliente può guadagnare semi. Lascia vuoto per nessun cooldown.
Abilitato	—	Attiva per abilitare o disabilitare questo codice senza eliminarlo. I codici disabilitati restituiscono un errore 403.

Codici & Limiti Spiegati

I codici e i loro limiti lavorano insieme per darti un controllo preciso su come vengono assegnati i semi:

Quantità di Semi

Ogni codice ha una quantità fissa di semi. Ogni volta che il webhook viene attivato con quel codice, il cliente riceve esattamente quel numero di semi. Ad esempio, se imposti "quiz_completato" a 5 semi, ogni chiamata webhook qualificata assegna 5 semi.

Massimi Semi per Cliente

Questo imposta un limite di vita per cliente per codice. È il totale di semi che quel cliente può guadagnare da questo codice specifico, non il numero di volte che può attivarlo.

Cooldown (Ore)

Imposta un tempo di attesa minimo tra le assegnazioni di semi per lo stesso cliente sullo stesso codice. Il timer di cooldown inizia dall'ultima assegnazione riuscita.

Formato della Richiesta

Invia una richiesta POST al tuo URL webhook con il seguente corpo JSON:

{
  "code": "il_tuo_codice_qui",
  "customer": {
    "email": "cliente@example.com",
    "shopify_customer_id": "12345",
    "first_name": "Giovanna",
    "last_name": "Rossi"
  },
  "metadata": {
    "quiz_score": 95,
    "source_page": "spring-quiz"
  }
}

* Almeno uno tra email o shopify_customer_id è richiesto. L'email è necessaria quando il cliente non esiste già in LoyaltyTree.

Verifica della Firma HMAC (Raccomandato)

Per verificare che le richieste provengano realmente dalla tua piattaforma (e non da qualcuno che ha trovato il tuo URL webhook), firma le tue richieste utilizzando HMAC-SHA256.

Header di firma supportati (LoyaltyTree controlla tutti questi):

• X-Webhook-Signature
• X-Hub-Signature-256
• X-Signature

Il valore della firma può essere o l'hash esadecimale grezzo o prefissato con sha256= (entrambi i formati sono accettati).

Alternativa: Autenticazione con Token Semplice

Se la firma HMAC non è possibile nella tua piattaforma, puoi passare il tuo segreto webhook come token semplice nell'header X-Token. LoyaltyTree lo confronterà direttamente con il tuo segreto.

Esempio: Firmare con Node.js

const crypto = require('crypto');

const payload = JSON.stringify({
  code: 'quiz_completato',
  customer: { email: 'giovanna@example.com' }
});
const signature = crypto
  .createHmac('sha256', 'il_tuo_segreto_webhook')
  .update(payload)
  .digest('hex');
fetch('https://loyaltytree.eco/webhooks/inbound/YOUR_SOURCE_ID', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Webhook-Signature': signature
  },
  body: payload
});

Esempio: Firmare con Python

import hmac, hashlib, json, requests

payload = json.dumps({
    "code": "quiz_completato",
    "customer": {"email": "giovanna@example.com"}
})
signature = hmac.new(
    b'il_tuo_segreto_webhook',
    payload.encode('utf-8'),
    hashlib.sha256
).hexdigest()
requests.post(
    'https://loyaltytree.eco/webhooks/inbound/YOUR_SOURCE_ID',
    headers={
        'Content-Type': 'application/json',
        'X-Webhook-Signature': signature
    },
    data=payload
)

Esempio: Utilizzare cURL (per testare)

curl -X POST https://loyaltytree.eco/webhooks/inbound/YOUR_SOURCE_ID \
  -H "Content-Type: application/json" \
  -H "X-Token: il_tuo_segreto_webhook" \
  -d '{"code":"quiz_completato","customer":{"email":"giovanna@example.com"}}'

Formato di Risposta

Risposta di Successo (200)

{
  "success": true,
  "seeds_awarded": 5,
  "transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customer_id": "f0e1d2c3-b4a5-6789-0123-456789abcdef"
}

Successo ma Limitato (200)

Quando un cooldown o un limite massimo di semi impedisce l'assegnazione, ricevi comunque una risposta 200 ma con 0 semi e un' spiegazione:

{
  "success": true,
  "seeds_awarded": 0,
  "message": "Cooldown attivo. Riprova tra 18 ora(e)."
}

// oppure
{
  "success": true,
  "seeds_awarded": 0,
  "message": "Massimo di semi (15) già assegnati per questo codice."
}

Risposte di Errore

Esempi di Casi d'Uso

Collegarsi con Zapier

Zapier è uno dei modi più popolari per connettere LoyaltyTree con centinaia di altre app. Stiamo costruendo un'integrazione dedicata di LoyaltyTree nello Zapier App Store, che renderà la configurazione ancora più semplice — cercala nel marketplace di Zapier.

Nel frattempo, puoi utilizzare l'azione Webhook di Zapier per connetterti subito:

Collegarsi con Make (Integromat)

Puoi anche utilizzare il modulo HTTP / Fai una richiesta di Make per inviare webhook a LoyaltyTree. Configuralo allo stesso modo di Zapier — imposta l'URL, aggiungi il corpo JSON con code e customer, e includi il tuo segreto nell'header X-Token.

Log dei Webhook

Ogni chiamata webhook in entrata viene registrata e visibile nella sezione Webhook in Entrata della tua pagina di Integrazioni. I log mostrano:

• Timestamp – Quando è stato ricevuto il webhook
• Fonte – Quale fonte l'ha ricevuto
• Stato – Successo o fallimento
• Dettagli – Codice utilizzato, semi assegnati o messaggio di errore
• Payload – Il corpo completo della richiesta (crittografato a riposo)

Utilizza i log per verificare che la tua integrazione funzioni correttamente e per risolvere eventuali problemi.

Risoluzione dei Problemi

Sicurezza

• Ogni fonte riceve un segreto webhook unico di 64 caratteri, generato automaticamente e crittografato a riposo
• I segreti possono essere rigenerati in qualsiasi momento dalle impostazioni della fonte (il vecchio segreto smette di funzionare immediatamente)
• I payload delle richieste sono crittografati nei log per la privacy
• La verifica della firma utilizza un confronto sicuro per il tempo per prevenire attacchi di timing
• Le fonti e i codici possono essere disabilitati singolarmente senza eliminarli