WebApps Process Response Reference

When a WebApp triggers a ProcessFlow execution, the value returned by your step code becomes the user-facing response contract. This guide explains which response fields are supported, how behavior changes by WebApp type, and how to keep responses predictable across browser, webhook, and API-style endpoints. Use it as the practical reference for returning success, error, redirect, and custom HTTP responses safely.

Return a consistent baseline response

Most implementations should always return success and then include either business data or a structured error. A stable baseline response shape reduces frontend branching logic and makes webhook consumers easier to maintain. The same shape also improves observability when you review logs or error traces.

type ProcessResult =
  | { success: true; data?: Record<string, unknown>; message?: string }
  | {
      success: false;
      error: { message: string; details?: string; code?: string };
    };

function buildValidationFailure(): ProcessResult {
  return {
    success: false,
    error: {
      message: "Validation failed",
      details: "Email is required",
      code: "VALIDATION_ERROR",
    },
  };
}

Understand field behavior by WebApp type

For browser-facing WebApps, action_url can trigger a redirect after a successful run, while plain data responses are rendered directly if no redirect is set. For webhook and callback patterns, responses are JSON-oriented and should keep machine-readable fields stable over time. For API-style WebApps, you can control http_code, headers, and raw body to return full HTTP responses from ProcessFlow logic.

Authentication response mapping also supports session issuance flows. If your process returns session_token (or fallback token fields), WebApps can set browser cookies using optional controls such as cookie_name, cookie_secure, and cookie_samesite.

Use API-style response controls when needed

API-routing use cases should return explicit status and headers when caller behavior depends on HTTP semantics. This is especially useful for external clients that branch on status codes or require strict Content-Type handling.

return {
    success: true,
    http_code: 201,
    headers: [
        "Content-Type": "application/json",
        "Cache-Control": "no-store"
    ],
    body: JSON.stringify([
        success: true,
        message: "Resource created",
        entity_id: "<ENTITY_ID>"
    ])
};

Validate response behavior with curl

You can test process-response behavior quickly by calling your WebApp endpoint with explicit auth and tenant headers. This helps confirm whether your response fields are being interpreted as JSON payloads, redirects, or custom HTTP output.

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

{
  "success": true,
  "data": {
    "entity_id": "<ENTITY_ID>",
    "status": "created"
  },
  "message": "Processed successfully"
}

Keep response contracts maintainable

Always return success explicitly, keep error payload keys consistent, and avoid switching field names between similar endpoints. If you use custom body, ensure it is a valid string and paired with matching Content-Type headers. For browser redirects, use action_url only when redirection is required, not as a general success mechanism.

Password handling in process output and logs

WebApp-triggered ProcessFlow executions now redact only fields named password (case-insensitive) in process execution output and execution logs. This includes process-level and step-level input_data / output_data surfaces shown in execution history and monitoring APIs.

• username is intentionally not redacted.
• Any key named password is returned as "****".
• Keep using password as the field name for secrets so redaction can be applied reliably.
• Prefer returning business results, tokens, and status flags in responses, not raw credentials.

Related guides

• WebApps Getting Started
• WebApps Built-in Functions
• ProcessFlow API Documentation

Reliable WebApp integrations depend on clear response contracts. When success, error, redirect, and API-style fields are used consistently, user-facing behavior stays predictable across every surface.