Cosa sono i Webhooks

I Webhooks di Webround rappresentano il modo più efficiente per sincronizzare i tuoi sistemi esterni con gli avvenimenti del tuo store in tempo reale. Invece di interrogare costantemente le nostre API (polling), sarà Webround a inviare notifiche al tuo server non appena accade qualcosa di rilevante.

Perché ascoltare i webhook

L'ascolto dei webhook ti permette di automatizzare flussi di lavoro complessi senza latenza:

• Sincronizzazione ERP/Logistica: Invia un ordine al magazzino non appena viene pagato.
• Notifiche Custom: Invia una mail o un messaggio Slack personalizzato ai tuoi clienti.
• Analisi Dati: Aggiorna il tuo database di BI in tempo reale senza sovraccaricare le API.

Come Webround integra i webhooks

Webround non si limita a inviare dati, ma garantisce un'infrastruttura di auditing e dispatching di livello enterprise, implementata con sistemi proprietari e code ad alte prestazioni.

• Affidabilità e Code: Utilizziamo sistemi di messaggistica avanzati per gestire i volumi di traffico, assicurando che ogni evento venga elaborato correttamente.
• Idempotenza: Ogni evento è marcato univocamente, permettendo al tuo sistema di ignorare eventuali duplicati.
• Deliverability: Gestiamo i retry automatici in caso di errore del tuo server, garantendo che il dato arrivi a destinazione.

Replay e auditing

Puoi eseguire il replay di eventi nella sezione "Eventi" della pagina dedicata ai Webhooks nel gestionale Webround Commerce del tuo store. Clicca su un evento e prosegui con "Invia di nuovo" per ricevere nuovamente l'evento.

Quali eventi sono disponibili

Puoi registrare un endpoint per gli eventi direttamente dal gestionale Webround Commerce. Accedi al tuo store, seleziona dalla sidebar la voce Webhooks e sei pronto a partire.

Configurazione

Puoi eseguire una configurazione granulare su quali eventi ascoltare per ogni singolo webhook. Al momento della creazione, dovrai collegare un endpoint (URL) di tua scelta. Webround invierà una richiesta POST all'indirizzo specificato con un payload JSON che rappresenta uno snapshot dell'entità e delle sue relazioni nel momento esatto in cui l'evento si è verificato.

Sicurezza e Segreti

Durante la configurazione, ti verrà mostrato un Segreto di Firma.

Importante

Conserva questo segreto con cura. Non ti sarà mai più mostrato in chiaro.

Per garantire la massima sicurezza, noi cifriamo il tuo segreto e lo decifriamo esclusivamente a livello di processo interno durante la fase di firma del payload. Non viene mai loggato né esposto, assicurando che solo il nostro sistema di dispatch possa generare una firma valida per i tuoi dati.

pericolo

Assicurati sempre di avere competenza e conoscenza di cosa accade nell'endpoint che riceve gli eventi del tuo store. Webround non manda dati sensibili, ma può inviare alcuni payload firmati e dati cliente, come nel caso di richieste di cancellazione dell'account, oppure nel caso di salvataggio di nuovi indirizzi di spedizione per lo specifico cliente.

Webround si occupa solo di inoltrare i dati in base alla tua configurazione. Una volta che i dati escono dalla piattaforma, è tua completa responsabilità assicurarne l'integrità e la correttezza, oltre al rispetto delle normative vigenti sulla privacy dei tuoi utenti.

Entità monitorate

Attualmente, puoi sottoscrivere eventi relativi a:

• Ordini: Creazione, aggiornamenti stato, pagamenti e rimborsi.
• Clienti dello store: Registrazioni, modifiche profilo e verifiche account.
• Prodotti, Varianti, SKU: Creazione prodotti, variazioni di prezzo, stock e attributi varianti.
• Abbonamenti: Gestione completa del ciclo di vita degli abbonamenti ricorrenti.

Tipi di dato

Ogni evento inviato da Webround, utilizza questo formato, allegando poi uno schema specifico per il payload più interno.

Campo	Tipo	Descrizione
envelopeId	uuid	Identificativo univoco del messaggio (ID del payload)
eventType	enum	Tipo di evento scatenato (es. order.created, order.paid, etc.)
initiatedBy	email, null, undefined	Email dell'utente o sistema che ha generato l'azione
storeId	uuid	Identificativo univoco dello store di appartenenza
occurredAt	isoDate	Timestamp ISO 8601 del momento esatto in cui l'evento è avvenuto
eventId	string	ID univoco dell'evento, utilizzabile come chiave di idempotenza