Apps

Le Apps sono applicazioni esterne che puoi installare direttamente nel tuo admin panel Webround. Non girano sull'infrastruttura di Webround — sono applicazioni indipendenti, sviluppate da te o da un developer di fiducia, accessibili come link diretto dal pannello di amministrazione.

---

App Private

Per ora, Webround supporta solo le App Private: applicazioni create e gestite direttamente dal merchant, visibili e accessibili solo nel proprio store. Non appaiono in nessun marketplace pubblico.

Una App Privata può essere qualsiasi cosa abbia un URL: un'applicazione web deployata su un dominio tuo, un Cloudflare Worker, un container su Cloud Run, un VPS, un servizio pubblico. L'unico requisito è che risponda a una chiamata HTTPS.

---

Autenticazione tramite redirect firmato

Quando apri un'app che richiede autenticazione (parametro needsSecret) dal tuo admin panel, Webround genera un URL di lancio firmato con HMAC-SHA256 e ti reindirizza verso di esso. L'URL include:

Parametro	Descrizione
wr_store	L'ID del tuo store
wr_app	L'ID dell'app
wr_ts	Timestamp di generazione in millisecondi
wr_sig	Firma HMAC-SHA256 calcolata sul payload

La firma è calcolata come:

HMAC-SHA256(secret, "{wr_store}:{wr_app}:{wr_ts}")

Il secret viene generato da Webround al momento dell'installazione dell'app e ti viene restituito una sola volta. Non viene mai mostrato di nuovo. Spetta a te condividerlo con il developer dell'app in maniera sicura, e all'app configurarlo come variabile d'ambiente.

Protezione dai replay attack

Come per gli Hook, il timestamp è fondamentale. L'app deve rifiutare qualsiasi richiesta con un timestamp più vecchio di 30 secondi — questo neutralizza il rischio che un attaccante che intercetti un URL di lancio possa riutilizzarlo in un secondo momento.

Gestione della sessione

L'app riceve i parametri firmati una sola volta — all'apertura. Dal quel momento in poi, gestisce la sessione autonomamente (cookie, token, o qualsiasi meccanismo preferisca). Il flusso tipico è:

1. L'utente apre l'app dall'admin panel Webround
2. L'app riceve i parametri firmati nell'URL
3. L'app verifica la firma e il timestamp
4. Se validi, crea una sessione locale e ripulisce l'URL dai parametri
5. Le richieste successive usano la sessione — nessun nuovo redirect necessario

// Esempio — verifica lato app (JS)
async function handleAuth(request, env) {
    const { wr_store, wr_app, wr_ts, wr_sig } = await request.json();

    if (!wr_store || !wr_app || !wr_ts || !wr_sig) {
        return Response.json({ ok: false }, { status: 401 });
    }

    // Protezione replay attack
    const age = Date.now() - parseInt(wr_ts);
    if (age > 30_000 || age < 0) {
        return Response.json({ ok: false, reason: 'Timestamp expired' }, { status: 401 });
    }

    // Verifica firma
    const payload = `${wr_store}:${wr_app}:${wr_ts}`;
    const key = await crypto.subtle.importKey(
        'raw',
        new TextEncoder().encode(env.APP_SECRET),
        { name: 'HMAC', hash: 'SHA-256' },
        false,
        ['verify']
    );
    const sigBytes = Uint8Array.from(
        wr_sig.match(/.{2}/g).map(b => parseInt(b, 16))
    );
    const valid = await crypto.subtle.verify(
        'HMAC', key, sigBytes,
        new TextEncoder().encode(payload)
    );

    if (!valid) return Response.json({ ok: false }, { status: 401 });

    // Crea sessione
    const sessionCookie = await createSessionCookie(env.APP_SECRET);
    return new Response(JSON.stringify({ ok: true }), {
        headers: {
            'Content-Type': 'application/json',
            'Set-Cookie': sessionCookie,
        }
    });
}

---

Esempio: un gestionale esterno integrato con Webround

Immagina di avere un sistema esterno per la gestione delle spedizioni — un'applicazione web che mostra gli ordini del tuo store e permette di creare spedizioni con il tuo corriere di fiducia.

Questo sistema non è sviluppato da Webround e non fa parte della piattaforma. Ma ha bisogno di accedere ai tuoi ordini. Come si integra in maniera sicura?

Con le API Key di Webround.

Crei una API Key con i soli permessi necessari — lettura ordini, update ordini — e la configuri come secret nell'applicazione esterna. L'app la usa per chiamare le API di Webround, e Webround la usa per autenticare ogni richiesta.

L'applicazione diventa un'App Privata nel tuo admin panel: la apri con un click, Webround la autentica tramite redirect firmato, e da quel momento l'app opera in completa autonomia — legge ordini, crea spedizioni, aggiorna stati.

suggerimento

La configurazione dell'autenticazione è totalmente libera. Webround ti consente di sapere che l'apertura dell'app parte dall'admin panel grazie alla presenza del payload firmato con la chiave condivisa, ma puoi anche ignorare questo meccanismo di firma e validazione, implementando un'app con un meccanismo di autenticazione unico.

Principio del minimo privilegio

Quando crei una API Key per un'app esterna, segui sempre questo principio:

• Una app, una key. Non condividere la stessa key tra applicazioni diverse.
• Solo i permessi necessari. Se l'app deve solo leggere ordini, la key non deve poter creare prodotti o modificare clienti.
• Invalida e rigenera se hai il minimo dubbio che la key sia stata compromessa. Una key rubata con permessi limitati fa molto meno danno di una key con accesso pieno.

Perché questo approccio?

Perché condividere dati e permessi con sistemi esterni quando puoi controllare esattamente cosa entra e cosa esce?

Con un sistema tradizionale finisci per installare plugin o app di terze parti a cui concedi accesso completo al tuo store — senza sapere cosa fanno davvero con quei dati, chi li custodisce, e quanto è sicura la loro infrastruttura.

Con Webround, l'integrazione è tua: tu sviluppi l'app (o la fai sviluppare), tu controlli il codice, tu gestisci i segreti. Webround fornisce gli strumenti per autenticare e autorizzare in maniera sicura — il resto rimane nel tuo dominio.

---

Prossimi Passi: Consulta la guida alle API Key per scoprire come creare e gestire le chiavi di accesso per le tue integrazioni.