Hook

Gli Hook sono richieste HTTP che il Router del tuo sito Webround esegue lato edge, durante il caricamento di una pagina, prima che il contenuto raggiunga il browser dell'utente.

Ogni hook punta a un endpoint esterno che controlli tu. Webround effettua la chiamata, riceve la risposta, e inietta il risultato nella pagina — permettendoti di arricchire il rendering con dati o logica completamente custom, senza toccare il codice del sito.

La visione

Webround è una piattaforma cloud multi-tenant. Questo significa che non puoi "aprire il server" e iniettare logica personalizzata come faresti con un'installazione on-premise.

Gli Hook risolvono questo problema in modo elegante: invece di ospitare la tua logica sul server di Webround, la ospiti tu, su un servizio che controlli completamente. Webround si limita a chiamarlo al momento giusto.

Questo approccio ha un vantaggio architetturale importante: isolamento totale tra tenant. La tua logica vive nel tuo sistema personale e non è condivisa con nessun altro tenant sulla piattaforma. Se domani vuoi aggiornare, sostituire o spegnere il tuo servizio, lo fai in autonomia e totale libertà.

Configurazione

Ogni hook è configurabile con:

Parametro	Descrizione
URL	L'endpoint esterno che Webround chiamerà
Metodo	`GET`, `POST`, `PUT`, `PATCH`, `DELETE`
Body	Payload opzionale da inviare con la richiesta
Pagine	Pattern di pagine su cui attivare l'hook (es. ``, `/product/`)
Audience	`all`, `human`, `bot` — utile per il dynamic rendering
Timeout	Tempo massimo di attesa in millisecondi (500–10000)
Secret	Se abilitato, Webround firma ogni richiesta con HMAC-SHA256

Editor vs Produzione

Gli hook funzionano anche nell'editor Webround, con una differenza importante: nell'editor il filtro per pagina non viene applicato. Tutti gli hook configurati vengono eseguiti indipendentemente dalla pagina che stai visualizzando. Il filtraggio per pattern di pagina è attivo esclusivamente sul sito di produzione.

Come vengono iniettati i dati

Quando il tuo endpoint risponde, Webround si aspetta sempre una risposta nella forma:

{ "data": { ... } }

Il contenuto di data viene iniettato nella pagina in base al tipo di iniezione configurato sull'hook (inject):

Tipo	Comportamento
`window`	I dati vengono esposti come `window.__WR_APPS__["slug"]` — accessibili da qualsiasi script nella pagina
`head-script`	Il contenuto di `data` viene iniettato come `<script>` nel `<head>`
`head-style`	Il contenuto di `data` viene iniettato come `<style>` nel `<head>`
`json-ld`	I dati vengono iniettati come `<script type="application/ld+json">` nel `<head>`
`body-start`	Il contenuto viene iniettato subito dopo il tag `<body>`
`body-end`	Il contenuto viene iniettato prima della chiusura `</body>`

Il tipo window è quello più comune per integrazioni dati: rende i dati disponibili globalmente nel browser, dove il tuo frontend può leggerli e usarli liberamente.

// Nel tuo frontend
const recensioni = window.__WR_APPS__["trustpilot"];
console.log(recensioni.average); // 4.7

Autenticazione

Se configuri un hook con un secret, Webround genera una chiave casuale e te la restituisce una sola volta al momento della creazione. Non viene mai mostrata di nuovo e non viene mai decifrata da Webround se non per firmare la richiesta verso di te.

Ogni chiamata verso il tuo endpoint includerà questi header:

X-WR-Timestamp: 1745000000
X-WR-Signature: t=1745000000,v1=a3f9c2...

La firma è calcolata come:

HMAC-SHA256(secret, "{timestamp}.{METHOD}.{pathname}.{body}")

dove body è il payload della richiesta (stringa vuota se assente).

Validazione

export default {
    async fetch(request, env) {
        const signature = request.headers.get('X-WR-Signature');
        const timestamp = request.headers.get('X-WR-Timestamp');
        const secret = env.HOOK_SECRET;

        if (secret) {
            if (!signature || !timestamp) {
                return new Response(JSON.stringify({ error: 'Missing signature' }), { status: 401 });
            }

            const ts = parseInt(timestamp);
            const now = Math.floor(Date.now() / 1000);
            if (Math.abs(now - ts) > 30) {
                return new Response(JSON.stringify({ error: 'Timestamp expired' }), { status: 401 });
            }

            const match = signature.match(/t=(\d+),v1=([a-f0-9]+)/);
            if (!match) {
                return new Response(JSON.stringify({ error: 'Invalid signature format' }), { status: 401 });
            }

            const method = request.method.toUpperCase();
            const pathname = new URL(request.url).pathname;
            const body = '';
            const payload = `${timestamp}.${method}.${pathname}.${body}`;

            const key = await crypto.subtle.importKey(
                'raw',
                new TextEncoder().encode(secret),
                { name: 'HMAC', hash: 'SHA-256' },
                false,
                ['verify']
            );

            const sigBytes = Uint8Array.from(
                match[2].match(/.{2}/g).map(b => parseInt(b, 16))
            );
            const valid = await crypto.subtle.verify(
                'HMAC', key, sigBytes,
                new TextEncoder().encode(payload)
            );

            if (!valid) {
                return new Response(JSON.stringify({ error: 'Invalid signature' }), { status: 401 });
            }
        }

        // La tua logica qui
        const data = { ... };

        return new Response(JSON.stringify({ data }), {
            headers: {
                'Content-Type': 'application/json',
                'Access-Control-Allow-Origin': '*'
            }
        });
    }
}

Il controllo sul timestamp neutralizza i replay attack: un attaccante che intercetta una richiesta legittima non può re-inviarla dopo che è scaduta la finestra di 30 secondi.

Esempio: recensioni Trustpilot

Supponiamo che tu voglia esporre i dati delle recensioni del tuo store sulle pagine prodotto. Invece di interrogare Trustpilot direttamente dal browser — esponendo le tue credenziali — crei un endpoint intermedio che Webround chiama lato edge.

Configurazione dell'hook:


URL	`https://hooks.example.com/trustpilot`
Metodo	`GET`
Inject	`window`
Pagine	`/product/*`
Audience	`human`
Secret	abilitato

Il tuo endpoint (/trustpilot) — Implementato come vuoi:

export default {
    async fetch(request, env) {
        // ... validazione firma (vedi sopra) ...

        const data = {
            average: 4.7,
            count: 128,
            distribution: { 5: 89, 4: 24, 3: 10, 2: 3, 1: 2 },
            featured: [
                { author: "Marco R.", rating: 5, text: "Prodotto eccellente, consegna rapida.", date: "2024-03-10" },
                { author: "Giulia T.", rating: 4, text: "Buona qualità, soddisfatta dell'acquisto.", date: "2024-02-28" },
                { author: "Luca M.", rating: 5, text: "Perfetto, lo ricomprerei.", date: "2024-01-15" },
            ]
        };

        return new Response(JSON.stringify({ data }), {
            headers: {
                'Content-Type': 'application/json',
                'Access-Control-Allow-Origin': '*'
            }
        });
    }
}

Nel tuo sito, i dati sono accessibili su:

const recensioni = window.__WR_APPS__["trustpilot"];
// { average: 4.7, count: 128, featured: [...] }

L'hook è configurato con audience human — i bot non ricevono il widget, ma questo non pregiudica l'indicizzazione SEO perché i dati rilevanti per Google (nome prodotto, prezzo, descrizione) sono già presenti nel rendering statico della pagina.

Un approccio flessibile

Con un'installazione on-premise, sei vincolato alla tecnologia del sistema che gestisce il tuo sito. Vuoi aggiungere logica custom? Devi farlo nella stessa tecnologia del server oppure installare software aggiuntivo, e far comunicare i pezzi in maniera spesso scomoda.

Con altri sistemi cloud, finisci per installare app di terze parti costose e dalla dubbia qualità, con cui condividi segreti e permessi che non controlli — esponendoti a problematiche di sicurezza che dipendono dalla solidità di qualcun altro, non tua.

Con Webround, usi la tecnologia che preferisci. Ti serve solo un URL che risponda. Puoi usare:

un Cloudflare Worker (serverless, zero cold start, globale)
un container Docker su un VPS personale
Google Cloud Run o qualsiasi altro servizio managed
un servizio che wrappa semplicemente un'API pubblica

Webround non sa e non si preoccupa di come è fatto il tuo endpoint. Sa solo chiamarlo, verificare la firma, e iniettare la risposta. Il resto è affar tuo — e questo è esattamente il punto.

Come gestire un hook Webround

Per gestire gli hook, recati nella scheda "Draft" del tuo account Webround.

Seleziona il Draft di interesse e procedi su "Gestisci integrazioni"

Clicca su "Gestisci integrazioni" per gestire le integrazioni specifiche di questo Draft.

Interagisci con il form degli hook per aggiungere, modificare o eliminare un hook specifico dall'Edge Router del tuo sito Webround

Al termine, salva l'hook. Puoi testare il tuo hook nell'editor Webround. L'hook inietterà i dati da subito anche nel sito pubblico.

Prossimi Passi: Consulta la guida alle App per scoprire come integrare applicazioni esterne direttamente nel tuo admin panel Webround.

La visione​

Configurazione​

Come vengono iniettati i dati​

Autenticazione​

Validazione​

Esempio: recensioni Trustpilot​

Come gestire un hook Webround​