WebApps User Guide

Document information

Canonical URL: /docs/05_apps-webhooks-and-surfaces/05_webapps-user-guide
Version: 2026-05-08
Tags: webapps, guides, reference

WebApps let you publish tenant-scoped user experiences that run ProcessFlow logic from forms, pages, and interactive UI elements. This guide walks through creating, publishing, and operating WebApps in a way that stays reliable for both users and operators. It focuses on practical setup decisions, response behavior, and day-two management patterns.

WebApp lifecycle illustration showing authoring, process integration, version publishing, public URL access, and execution log monitoring.

Understand what a WebApp does

A WebApp is an HTML/CSS/JavaScript surface connected to a ProcessFlow process. Users interact with the page, submit data, and receive responses based on process output contracts such as success messages, errors, redirects, or API-style payloads. This model lets teams deliver user-facing workflows quickly without building separate frontend and backend deployment stacks for each use case.

WebApps are versioned, so draft changes can be prepared and reviewed before publishing. Only published versions are publicly accessible through tenant-specific URLs, which keeps release control predictable.

Create your first WebApp

Start in the WebApps management area, create a new entry, and define the tenant, executing user, and display name. If the page should trigger automation, attach the appropriate ProcessFlow process at creation time or later during edits. Treat this process association as part of your API contract because submitted form fields become process input.

<form method="post">
  <label for="name">Name</label>
  <input id="name" name="name" type="text" required />

  <label for="email">Email</label>
  <input id="email" name="email" type="email" required />

  <button type="submit">Submit</button>
</form>

Publish and manage versions safely

Every WebApp change should be treated as a versioned release. Save edits as drafts, validate behavior, then publish the intended version once QA is complete. This avoids accidental production changes and gives teams clear rollback points when needed.

In day-to-day operations, use execution logs to verify requests, duration, and response status. Logs are especially useful when process output shapes change, because frontend behavior may depend on fields like action_url, message, or structured error payloads.

Integrate through API workflows

Teams managing WebApps via scripts or CI pipelines can automate create and publish operations through the API. Keep tenant headers and authentication explicit so release actions remain deterministic across environments.

const baseUrl = "https://api.example.com/api/v1/webapps";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

async function publishWebAppVersion(webappId: string, version: number): Promise<void> {
  const response = await fetch(`${baseUrl}/${encodeURIComponent(webappId)}/publish`, {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      "X-Tenant-ID": tenantId,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ version }),
  });
  if (!response.ok) throw new Error(`Publish failed: ${response.status}`);
}

curl -X POST "https://api.example.com/api/v1/webapps/<ENTITY_ID>/publish" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 2
  }'

{
  "success": true,
  "message": "Version published successfully"
}

Follow production best practices

Design forms with semantic labels and clear validation messaging so users can correct input quickly. Keep CSS and JavaScript maintainable by reusing library classes and avoiding brittle page-specific logic where possible. In process integration, return consistent response structures and avoid exposing sensitive values in user-facing output.

If a WebApp is not behaving as expected, first confirm it is published, then inspect execution logs and linked process behavior. Most incidents are caused by draft/published mismatch, missing process binding, or response-field contract drift.