Apps

Apps are external applications that you can install directly into your Webround admin panel. They do not run on Webround's infrastructure — they are independent applications, developed by you or a trusted developer, accessible as a direct link from the administration panel.

---

Private Apps

For now, Webround only supports Private Apps: applications created and managed directly by the merchant, visible and accessible only within their own store. They do not appear in any public marketplace.

A Private App can be anything that has a URL: a web application deployed on your own domain, a Cloudflare Worker, a container on Cloud Run, a VPS, a public service. The only requirement is that it responds to an HTTPS call.

---

Authentication via Signed Redirect

When you open an app that requires authentication (the needsSecret parameter) from your admin panel, Webround generates a launch URL signed with HMAC-SHA256 and redirects you to it. The URL includes:

Parameter	Description
wr_store	Your store ID
wr_app	The app ID
wr_ts	Generation timestamp in milliseconds
wr_sig	HMAC-SHA256 signature calculated on the payload

The signature is calculated as:

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

The secret is generated by Webround at the time of app installation and is returned to you only once. It is never shown again. It is up to you to share it securely with the app developer and for the app to configure it as an environment variable.

Replay Attack Protection

As with Hooks, the timestamp is crucial. The app must reject any request with a timestamp older than 30 seconds — this neutralizes the risk that an attacker who intercepts a launch URL could reuse it at a later time.

Session Management

The app receives the signed parameters only once — upon opening. From that moment on, it manages the session independently (cookies, tokens, or any mechanism it prefers). The typical flow is:

1. The user opens the app from the Webround admin panel
2. The app receives the signed parameters in the URL
3. The app verifies the signature and the timestamp
4. If valid, it creates a local session and clears the parameters from the URL
5. Subsequent requests use the session — no new redirect is necessary

// Example — app-side verification (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 });
    }

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

    // Signature verification
    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 });

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

---

Example: an external management system integrated with Webround

Imagine you have an external system for shipping management — a web application that displays your store's orders and allows you to create shipments with your preferred courier.

This system is not developed by Webround and is not part of the platform. But it needs to access your orders. How is it integrated securely?

With Webround API Keys.

You create an API Key with only the necessary permissions — read orders, update orders — and configure it as a secret in the external application. The app uses it to call the Webround APIs, and Webround uses it to authenticate every request.

The application becomes a Private App in your admin panel: you open it with a click, Webround authenticates it via a signed redirect, and from that moment on, the app operates in complete autonomy — it reads orders, creates shipments, and updates statuses.

tip

Authentication configuration is completely flexible. Webround allows you to know that the app launch starts from the admin panel thanks to the presence of the payload signed with the shared key, but you can also ignore this signing and validation mechanism by implementing an app with a unique authentication mechanism.

Principle of Least Privilege

When you create an API Key for an external app, always follow this principle:

• One app, one key. Do not share the same key between different applications.
• Only necessary permissions. If the app only needs to read orders, the key should not be able to create products or modify customers.
• Invalidate and regenerate if you have the slightest doubt that the key has been compromised. A stolen key with limited permissions does much less damage than a key with full access.

Why this approach?

Why share data and permissions with external systems when you can control exactly what goes in and out?

With a traditional system, you end up installing third-party plugins or apps that you grant full access to your store — without knowing what they really do with that data, who guards it, and how secure their infrastructure is.

With Webround, the integration is yours: you develop the app (or have it developed), you control the code, you manage the secrets. Webround provides the tools to authenticate and authorize securely — the rest remains within your domain.

---

Next Steps: Consult the API Keys guide to discover how to create and manage access keys for your integrations.