JeriCommerce registra le interazioni significative dei clienti con il programma fedeltà. Quando colleghi l'integrazione Custom API, tutti gli eventi vengono inviati come webhook HTTP POST all'endpoint configurato. Puoi così creare automazioni personalizzate, sincronizzare dati o attivare flussi in qualsiasi sistema.

Configurazione

Aggiungi l'endpoint webhook in Settings → Integrations → API, attiva Events e salva. Da quel momento, ogni evento idoneo del cliente viene inviato al tuo URL con una richiesta POST.

Autenticazione

Ogni richiesta include un header x-jericommerce-hmac-sha256 con una firma cifrata HMAC-SHA256 usando il secret mostrato nella pagina dell'integrazione. Convalida la firma sul server per verificare che la richiesta provenga da JeriCommerce e impedire falsificazioni.

Il tipo di evento viene inviato nell'header x-jericommerce-event-type. Usalo per indirizzare il payload al gestore corretto.

Errori di consegna e nuovi tentativi

Gli errori di rete e le risposte 408, 429 e 5xx vengono ritentati con un intervallo esponenziale, fino a 10 tentativi. Gli errori permanenti lato client, come 401, 403, 404 e 410, non vengono ritentati. Rendi idempotente l'endpoint, perché un errore temporaneo può comunque causare più invii dello stesso evento.

JeriCommerce conteggia gli errori permanenti consecutivi per ciascuna integrazione API. Dopo 10 errori permanenti, disattiva Events per quell'integrazione e interrompe l'invio all'endpoint non funzionante. Correggi l'endpoint e riattiva Events nelle impostazioni dell'integrazione API. Una consegna riuscita azzera il conteggio degli errori consecutivi.

Payload di base

Tutti i webhook condividono questa struttura:

{
  "email": "customer@example.com",
  "id": "event-uuid",
  "customerId": "customer-uuid",
  "campaignId": "campaign-uuid",
  "url": "https://...",
  "browser": "Chrome 120",
  "createdAt": "2026-03-08T12:00:00Z",
  "properties": { ... }
}

I campi indicati come facoltativi potrebbero non comparire in ogni evento:

  • campaignId: presente solo quando l'evento è collegato a una campagna specifica
  • url e browser: presenti solo per eventi provenienti dal web

Tutti gli eventi

Ecco l'elenco completo dei 19 eventi inviati al webhook. La colonna Nome evento corrisponde al valore dell'header x-jericommerce-event-type. La colonna Proprietà chiave mostra i campi disponibili nell'oggetto properties.

Nome evento Quando si attiva Proprietà chiave
Cliente
Customer created Nuovo cliente registrato (non durante la sincronizzazione iniziale) email, origin, referral, utmCampaign, utmMedium, utmSource, firstName, lastName, phoneNumber
Customer birthday Verifica giornaliera automatica dei compleanni, verso le 9:00 UTC age (calcolato dalla data di nascita)
Customer scanned Cliente scansiona un codice NFC in una sede fisica tramite Shopify POS Contesto della sede e del dispositivo
Customer tapped Cliente tocca un dispositivo VTAP/NFC Contesto del dispositivo
Wallet pass
Wallet pass requested Cliente richiede un link di download del wallet pass email, referral, downloadLink, utmCampaign, utmSource, utmMedium
Wallet pass installed Cliente aggiunge il pass ad Apple Wallet o Google Wallet referral, utmCampaign, utmSource, utmMedium
Wallet pass uninstalled Cliente rimuove il pass dal wallet referral, utmCampaign, utmSource, utmMedium
Fidelizzazione
Balance changed Punti fedeltà aggiunti o rimossi, per acquisti, rimborsi o modifiche manuali amount, reference, previous (saldo prima della modifica), pointsToNextReward, nextRewardName
Tier changed Cambia il livello fedeltà del cliente, ricalcolo giornaliero alle 5:00 o modifica del saldo previous (nome livello), current (nome livello)
Coupon
Coupon assigned Codice coupon assegnato al cliente code, header, body, slug, assignedFrom, installUrl
Coupon expiring Codice coupon assegnato e non usato, in scadenza il giorno solare successivo nel fuso orario del negozio couponId, couponCodeId, couponSlug, code, expiresAt
Coupon pass installed Cliente aggiunge un coupon pass ad Apple Wallet o Google Wallet referral, utmCampaign, utmSource, utmMedium
Coupon pass uninstalled Cliente rimuove un coupon pass dal wallet referral, utmCampaign, utmSource, utmMedium
Gift card
Gift card sent Un amministratore invia una gift card al cliente code, header, body, slug, assignedFrom, installUrl, mailSent
Premi
Reward redeemable Un premio diventa riscattabile dal cliente rewardId, rewardLink, rewardTitle, rewardValue, rewardCost, customerRemainingBalance
Reward redeemed Cliente riscatta un premio rewardId, rewardLink, rewardTitle, code
Reward refunded Un amministratore rimborsa un premio riscattato in precedenza claimId
Coinvolgimento
Wallet click Cliente fa clic su un link all'interno del wallet pass url, browser, utmCampaign, utmSource ("wallet"), utmMedium ("wallet_pass")
Wallet visit Cliente visita o apre la web app del wallet pass name, url, browser, referral, utmCampaign, utmSource, utmMedium

La configurazione è completa. Il tuo endpoint riceverà dati in tempo reale per le interazioni cliente con JeriCommerce.

Coupon expiring

L'evento Coupon expiring è disponibile tramite la mappatura generica degli eventi API. Viene emesso per un codice coupon assegnato a un cliente, non ancora usato e in scadenza il giorno solare successivo secondo il fuso orario Shopify del negozio. Se JeriCommerce non riesce a leggere il fuso orario, usa UTC. Non è un promemoria esattamente 24 ore prima.

Le proprietà dell'evento includono couponId, couponCodeId, couponSlug, code ed expiresAt. Usalo per creare una tua automazione. Non invia email o notifiche push automaticamente e non è disponibile come trigger Shopify Flow.