@salsita-ai/sdk 0.50.0-develop.5a0bcdee42 → 0.50.0-develop.5ac9723d62

package/dist/docs/phoenix/webhooks.mdx

@@ -10,30 +10,57 @@
   - [Dynamic Resources Factory](#dynamic-resources-factory)
   - [Backend Data Handler](#backend-data-handler)
 
-To support project specific finalization workflows, authentication and custom integrations, platform provides a way to define webhooks.
-These webhooks are deployed on aws lambda and can be triggered by specific platform triggers. Currently we support three types of webhooks.
+To support project specific finalization workflows, authentication and custom integrations, the platform runs a project webhook: one bundle, deployed as a cloud function (AWS Lambda), that the platform calls for these operations:
 
-- Configurator Finalization
-- Admin Finalization
-- Auth Hook
+- **auth** - creating or refreshing a configurator session ([Auth Hook](#auth-hook))
+- **fetchBackendData** - server-side data for the configurator ([Backend Data Handler](#backend-data-handler))
+- **finalize** - configurator finalization ([Configurator Finalization](#configurator-finalization)) and Admin finalization when an admin publishes from Project Admin ([Admin Finalization](#admin-finalization))
+- **callback** - the result of a configurator finalization ([Callback Hook / Result](#callback-hook--result))
+- **assistantSetup** - the assistant's setup for a session, when the spec configures the assistant
+
+Under `phoenix dev` the webhook runs on the developer's machine, and the platform reaches it through the development webhook tunnel instead of the cloud function.
 
 ## Webhook builders
 
-Phoenix provides domain-aware builders through the global `phx.webhooks` namespace. These are automatically generated from your `spec/application.yaml` configuration and available without imports.
+Phoenix provides domain-aware builders through the global `phx.webhooks` namespace. These are automatically generated from your spec into `.phoenix/webhook-builders.ts` and available without imports.
 
 **Available builders and factories:**
 
-- `phx.webhooks.webhookBuilder` - Main webhook builder for composing handlers
-- `phx.webhooks.finalizeHandlerBuilder` - Configurator finalization handler builder
-- `phx.webhooks.adminFinalizeHandlerBuilder` - Admin finalization handler builder
 - `phx.webhooks.authHandlerBuilder` - Authentication handler builder
+- `phx.webhooks.webhookBuilder` - Main webhook builder for composing handlers: `withAuthHook`, `withFetchBackendData`, `withConfiguratorFinalize` and `build()`
 - `phx.webhooks.taskFactory` - Factory for creating finalization tasks
+- `phx.webhooks.finalizeHandlerBuilder` - Configurator finalization handler builder; pass its `build()` result to `withConfiguratorFinalize`
 - `phx.webhooks.callbackBuilder` - Builder for callback handlers
 - `phx.webhooks.prefetchBuilder` - Builder for prefetch handlers
 - `phx.webhooks.dynamicResourcesFactory` - Factory for dynamic resource creation
 
+There is no builder for Admin finalization: the SDK builds it itself (see [Admin Finalization](#admin-finalization)).
+
 ### Webhook Entry Point
 
+Your webhook is the default export of `src/webhooks/index.ts`. With the application-spec pipeline (see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)), the file is yours to create; sync does not write it. A project without it gets a built-in webhook, so it builds and deploys with no webhook code. The built-in webhook has one handler, an anonymous auth handler, which the platform calls only when `spec/application.yaml` sets `useAuthHook`. The legacy pipeline writes the file with that webhook on the first sync.
+
+Create `src/webhooks/index.ts` when the project needs its own handlers: finalization, backend data, or an auth handler that does more than start an anonymous session.
+
+If `useAuthHook` or `useClerk` is enabled without this file, sync, build, clean and dev report `AUTH_WITHOUT_PROJECT_WEBHOOK` and generation continues with the anonymous-only built-in webhook. This warning also applies when `useAuthHook: false` is explicit alongside `useClerk: true`. Add a default-exported webhook with the required Clerk or custom auth handlers, or disable the settings if they are unintended.
+
+The smallest file is the built-in webhook itself:
+
+```ts
+// src/webhooks/index.ts
+const authHandler = phx.webhooks.authHandlerBuilder
+  .withAnonymousHandler(async () => ({ success: true, data: {}, role: 'anonymous' }))
+  .build()
+
+export default phx.webhooks.webhookBuilder.withAuthHook(authHandler).build()
+```
+
+The next `phoenix sync` or `phoenix build`, or the rebuild of a running `phoenix dev`, uses the file; deleting it brings the built-in webhook back. A webhook needs at least one handler, and a project with any other file in `src/webhooks/` must have `index.ts`.
+
+Only `src/webhooks/index.ts` is imported: other files in `src/webhooks/` run only when it imports them. Sync generates the rest: `.phoenix/webhook.ts` (the bundle's entry, which exports your webhook or the built-in one), `.phoenix/webhook-builders.ts` (the `phx.webhooks` builders) and `.phoenix/webhooks.config.ts` (the reader of [environment variables](#environment-variables)).
+
+A webhook with more handlers:
+
 ```ts
 // src/webhooks/index.ts
 import { authHandler } from './handlers/auth-handler.js'
@@ -63,16 +90,35 @@ Environment variables for webhooks are defined in `spec/application.yaml` under
 # spec/application.yaml
 env:
   webhook:
-    EMAIL_TO:
-      type: email
+    CRM_API_URL:
+      type: url
+      required: true
+      devDefault: http://localhost:4000
+    CRM_API_TOKEN:
+      type: str
+      required: true
     EMAIL_FROM:
-      type: email
+      type: str
+      default: configurator@example.com
+    WOOCOMMERCE_SHOP_URL:
+      type: url
+    WOOCOMMERCE_API_KEY:
+      type: str
     GOOGLE_SPREADSHEET_ID:
       type: str
-    GOOGLE_SERVICE_ACCOUNT_KEY:
+    GOOGLE_SERVICE_ACCOUNT_JSON:
       type: str
 ```
 
+Each entry accepts only these keys:
+
+- `type` - `bool`, `str`, `num` or `url`
+- `default` - the value when the variable is not set
+- `devDefault` - the value when the variable is not set under `phoenix dev`, which builds the webhook outside production
+- `required` - `true` when the variable must be set
+
+A variable that is neither required nor defaulted is `undefined` when it is not set, so code checks it before use.
+
 ### Using Environment Variables
 
 Environment variables are available through the `phx.webhooksEnv` global:
@@ -80,11 +126,11 @@ Environment variables are available through the `phx.webhooksEnv` global:
 ```ts
 // src/webhooks/handlers/some-handler.ts
 const GOOGLE_SPREADSHEET_ID = phx.webhooksEnv.GOOGLE_SPREADSHEET_ID
-const GOOGLE_SERVICE_ACCOUNT_KEY = phx.webhooksEnv.GOOGLE_SERVICE_ACCOUNT_KEY
+const GOOGLE_SERVICE_ACCOUNT_JSON = phx.webhooksEnv.GOOGLE_SERVICE_ACCOUNT_JSON
 ```
 
-These variables are automatically injected from the project's parameter store in the CI pipeline and are built into the bundled lambda code deployed to AWS.
-They cannot be changed after deployment - redeployment is required to update them.
+The values are inlined into the webhook bundle when it is built, so a changed value takes effect only after a restart of `phoenix dev`, or a new deploy on a deployed environment.
+Deployed builds take the values from the environment variables a workspace super admin sets in Studio (see [SDK Builder Workflow](?path=/docs/phoenix-sdk-builder-workflow--docs)); `phoenix dev` reads them from the project's `.env`.
 
 ## Configurator Finalization
 
@@ -148,7 +194,7 @@ resources:
     s3Key: clientImage
 ```
 
-These resources are automatically made available as typed properties in task handlers via the `resources` parameter.
+These resources are automatically made available as typed properties in task handlers via the `resources` parameter. Two static resources with the same name are an error: `phoenix check` and `phoenix build` report the second entry (`DUPLICATE_RESOURCE_NAME`).
 
 #### Task Payload
 
@@ -160,7 +206,7 @@ Additionally, tasks receive:
 - `prefetchedData`: Results from [prefetch handlers](#prefetch-tasks), if configured
 - `backendData`: Server-side data from [backend data handlers](#backend-data-handler), if configured
 
-Before the task is executed, the domain state is validated using the configurator's domain and its violations. If any violations are found (warning level and up), the task is not executed and the error is returned to the client.
+Before the task is executed, the domain state is validated using the configurator's domain and its violations. If any violations are found (warning level and up), the task is not executed and the finalization fails; the client learns only that it failed, and the reason is in the webhook's log.
 
 #### Task Context
 
@@ -190,26 +236,28 @@ export interface TaskContext<
 
 #### Static assets
 
-Some tasks may need access to static assets, like logos, fonts, scripts, blender files, etc... The deployment client allows to upload public and private assets.
-To make these assets available to the tasks, put them in `/assets/private` and `/assets/public` folders respectively.
+Some tasks may need access to static assets, like logos, fonts, scripts, blender files, etc...
+Put files only the server uses (Blender templates, models, render scripts) in `/assets/private`, and files that must be reachable by URL (logos, fonts) in `/assets/public`. Both folders are uploaded with the deployment; a task resolves a public file's URL with `ctx.getPublicAssetUrl(path)`.
 
 ### Task execution order
 
-The webhook finalization follows a specific execution order to ensure proper data flow and resource availability:
+The webhook prepares the finalization, then the platform runs its tasks:
 
-1. **Backend Data Handler** (if configured) - Fetches server-side data
+1. **Backend Data Handler** (if configured) - The webhook runs it again before every configurator finalization; a failure fails the finalization
 2. **Prefetch Handler** (if configured) - Data preparation and external system setup
-3. **Task execution in fixed order** - Tasks run sequentially to allow resource reuse:
-   - GenerateConfigurationLinkTask / PublishRevisionTask
-   - GenerateImages
-   - GenerateCsv
-   - GeneratePdf
-   - SendEmail
-   - SendHttpRequest
-   - WooCommerceAddToCart
-   - EditGoogleSpreadsheet
-4. **Callback Handler** (if configured) - Process results and return final response
-5. **Result** - Final response returned to client
+3. **Task collection** - The webhook calls the `withTask` and `withResources` handlers and returns the tasks and resources to the platform
+4. **Task execution by type** - The server runs tasks by type, not in `withTask` order. Tasks of one type run in parallel, except server renders, which the rendering worker takes one at a time:
+   1. As child jobs: `GenerateConfigurationLink` (and the `Publish*` tasks of Admin finalization) on the server, and `GenerateImages` on the rendering worker
+   2. Then, on the finalize worker: `GenerateCsv`, then `GeneratePdf` and `GenerateStaticPdf`
+   3. The generated PDFs and CSVs are uploaded to their `s3Key` - only when the finalization also has a `CallLambdaBack` or `WooCommerceAddToCart` task
+   4. `SendEmail` and `SendStaticEmail`
+   5. `SendHttpRequest`
+   6. `WooCommerceAddToCart`
+   7. `EditGoogleSpreadsheet`
+   8. `CallLambdaBack` - the [callback](#callback-hook--result), last
+5. **Result** - The callback's result is returned to the client; without a callback the client receives no result
+
+So a PDF or an email can use the links and rendered images, and an email can attach the generated PDFs and CSVs. Nothing is retried or rolled back: when a task fails, the finalization fails and what already ran stays done.
 
 ### GenerateConfigurationLink Task
 
@@ -391,7 +439,7 @@ ctx.emailTaskBuilder.withSubject(msg`Your configuration`)
 In React templates, use `<Trans>` for inline strings and `<HtmlHelpers.Localized>` to render message descriptors:
 
 ```tsx
-import { Trans } from '@lingui/macro'
+import { Trans } from '@lingui/react/macro'
 
 import { HtmlHelpers } from '@salsita-ai/sdk/webhook'
 
@@ -456,7 +504,7 @@ The template file:
 
 ```tsx
 // src/webhooks/handlers/configurator-finalize-handler/tasks/pdf-template.tsx
-import { Trans } from '@lingui/macro'
+import { Trans } from '@lingui/react/macro'
 
 import { HtmlHelpers, PdfHelpers, ResourceHelpers } from '@salsita-ai/sdk/webhook'
 
@@ -578,7 +626,7 @@ except for resource reference interpolation.
 
 ```tsx
 // src/webhooks/handlers/configurator-finalize-handler/tasks/email-task.tsx
-import { msg } from '@lingui/macro'
+import { msg } from '@lingui/core/macro'
 
 import { EmailTemplate } from './email-template.js'
 
@@ -603,7 +651,7 @@ export const simpleEmailTask = phx.webhooks.taskFactory.createSendEmailTask((res
 
 ```tsx
 // src/webhooks/handlers/configurator-finalize-handler/tasks/email-template.tsx
-import { Trans } from '@lingui/macro'
+import { Trans } from '@lingui/react/macro'
 
 import { EmailHelpers, ResourceHelpers } from '@salsita-ai/sdk/webhook'
 
@@ -681,11 +729,26 @@ To avoid sending real emails through SES during local development, set the `EMAI
 
 ### SendHttpRequest Task
 
-Sends a HTTP request to the provided URL.
+Sends an HTTP request to the provided URL with `method` (`GET` by default), `headers` and a string `body`. A body needs a method other than `GET`. An answer outside 2xx fails the finalization; there is no timeout and no retry.
+
+Following example shows a task that posts the configuration to a CRM, with the URL and token from [environment variables](#environment-variables):
+
+```ts
+// src/webhooks/handlers/configurator-finalize-handler/tasks/crm-quote-task.ts
+export const crmQuoteTask = phx.webhooks.taskFactory.createSendHttpRequestTask((_resources, data, ctx) => {
+  const chair = ctx.domain.getRoot$Entity(data.state)
 
-TODO: Provide a simple example
+  return {
+    type: 'SendHttpRequest',
+    url: `${phx.webhooksEnv.CRM_API_URL}/quotes`,
+    method: 'POST',
+    headers: { authorization: `Bearer ${phx.webhooksEnv.CRM_API_TOKEN}`, 'content-type': 'application/json' },
+    body: JSON.stringify({ configurationId: data.configurationId, model: chair.label }),
+  }
+})
+```
 
-Following example shows a simple task that sends a HTTP request to the provided URL.
+Full definition of the task is defined in the `SendHttpRequestTask` type.
 
 ```ts
 /**
@@ -712,11 +775,52 @@ export interface SendHttpRequestTask {
 }
 ```
 
-### WoocommerceAddToCart Task
+### WooCommerceAddToCart Task
 
 Adds the configured product to a WooCommerce cart. This task is part of the WooCommerce integration, which also requires the WordPress plugin —
-see [Integrations / WooCommerce / Overview](/docs/integrations-woocommerce-overview--docs) for the full picture and
-[Integrations / WooCommerce / Local Development](/docs/integrations-woocommerce-local-development--docs) for a local setup guide.
+see [Integrations / WooCommerce / Overview](?path=/docs/integrations-woocommerce-overview--docs) for the full picture and
+[Integrations / WooCommerce / Local Development](?path=/docs/integrations-woocommerce-local-development--docs) for a local setup guide.
+
+The task takes:
+
+- `items` - each with a `product`, and optionally `productName`, `productDescription`, `price`, `quantity`, `image` (the name of a declared `Image` resource, not a URL), `customData` and `resources` listed in the order as `{ type, name, label }`
+- `fees` - optional, each `{ type: 'Flat' | 'Percentage', name, amount, taxable?, taxClass? }`
+- `session` and `addToCartUrl` - the Phoenix WordPress plugin puts `session` and a relative `add-to-cart-url` as attributes on the configurator tag; the configurator passes both unchanged in the finalize data. The task's `addToCartUrl` must be absolute, and the platform sends the API key to it, so the webhook builds it from the shop's URL in a webhook environment variable and refuses any other origin: a URL taken from the browser as-is would let anyone have the key sent to a server of their choosing
+- `apiKey` - the key configured in the plugin, kept in a webhook environment variable
+
+The example assumes `cartSession` and `addToCartUrl` in the `finalizeData` schema and skips the task when the configurator does not run in the shop:
+
+```ts
+// src/webhooks/handlers/configurator-finalize-handler/tasks/cart-task.ts
+export const cartTask = phx.webhooks.taskFactory.createWooCommerceAddToCartTask((resources, data, ctx) => {
+  const { cartSession, addToCartUrl } = data.finalizeData
+  const shopUrl = phx.webhooksEnv.WOOCOMMERCE_SHOP_URL
+  const apiKey = phx.webhooksEnv.WOOCOMMERCE_API_KEY
+
+  if (cartSession === undefined || addToCartUrl === undefined || shopUrl === undefined || apiKey === undefined) {
+    return null
+  }
+
+  // The platform sends the API key to this URL, so it may only point at the shop
+  const cartEndpoint = new URL(addToCartUrl, shopUrl)
+
+  if (cartEndpoint.origin !== new URL(shopUrl).origin) {
+    throw new Error(
+      `The add-to-cart URL ${addToCartUrl} is not on the shop ${shopUrl}. Pass the plugin's add-to-cart-url unchanged.`
+    )
+  }
+
+  const chair = ctx.domain.getRoot$Entity(data.state)
+
+  return {
+    type: 'WooCommerceAddToCart',
+    session: cartSession,
+    addToCartUrl: cartEndpoint.href,
+    apiKey,
+    items: [{ product: 'custom-chair', productName: chair.label, quantity: 1, image: resources.simpleImage }],
+  }
+})
+```
 
 ### EditGoogleSpreadsheet Task
 
@@ -726,8 +830,8 @@ Google spreadsheet and share it with a service account created for this purpose.
 
 For details on how to create a service account, see the [official documentation](https://cloud.google.com/iam/docs/service-accounts-create).
 
-To edit the spreadsheet, the lambda returns a `EditGoogleSpreadsheetTask` object in tasks. The lambda specifies the
-service account key (content of credentials json file), the id of the spreadsheet (from url), and an array of edits to make to the spreadsheet.
+To edit the spreadsheet, the webhook returns an `EditGoogleSpreadsheetTask` object in tasks. The task specifies the
+service account key (the parsed content of the credentials JSON file), the id of the spreadsheet (from its URL), and an array of edits to make to the spreadsheet.
 
 ```ts
 export interface EditGoogleSpreadsheetTask {
@@ -755,19 +859,21 @@ There are currently two types of edit mode available:
 - **overwrite** overwrite the contents of one or more ranges of cells in the spreadsheet
 - **append** append new rows of cells
 
-Within each edit, the lambda provides one or more operations to perform. Each operation relates to a single range of cells and their corresponding new values.
+Within each edit, the task provides one or more operations to perform. Each operation relates to a single range of cells and their corresponding new values.
 
 ```ts
+export type GoogleSpreadsheetCellValue = string | number | boolean | { type: 'ConfigurationLink'; name: string }
+
 export interface GoogleSpreadsheetEdit {
   /**
    * Ranges of cells to edit
    */
-  ranges: Record<string, Array<Array<string | number | boolean>>>
+  ranges: Record<string, GoogleSpreadsheetCellValue[][]>
 
   /**
    * Edit mode
    */
-  mode: GoogleSpreadsheetEditMode
+  mode: 'append' | 'overwrite'
 }
 ```
 
@@ -776,51 +882,62 @@ The operations are stored in the `ranges` property. The keys represent reference
 In append mode, the key represents the range of columns that the appended row or rows will span. Cells in the given range are scanned, and data is inserted into the first row where all cells in the range of that row and all subsequent rows are empty.
 
 The values are two dimensional arrays of corresponding cell content to write. The major dimension is always 'rows'. That means
-that the outer array represents rows and the inner arrays represent cells arranged in columns.
+that the outer array represents rows and the inner arrays represent cells arranged in columns. A cell is a string, number or boolean, written exactly as given (raw, not parsed as a formula), or `{ type: 'ConfigurationLink', name }`, replaced with a link generated in the same finalization.
 
 example:
 
 ```ts
-const editSpreadsheetTask: EditGoogleSpreadsheetTask = {
-  type: 'EditGoogleSpreadsheet',
-  spreadsheetId: phx.webhooksEnv.GOOGLE_SPREADSHEET_ID,
-  credentials: <service account credentials>,
-  edits: [
-    {
-      ranges: {
-        'Orders!A:B': [
-          ['Custom Chair', 1000],
-          ['Custom Table', 2000]
-        ],
+// src/webhooks/handlers/configurator-finalize-handler/tasks/spreadsheet-task.ts
+export const spreadsheetTask = phx.webhooks.taskFactory.createEditGoogleSpreadsheetTask((resources, data) => {
+  const spreadsheetId = phx.webhooksEnv.GOOGLE_SPREADSHEET_ID
+  const serviceAccount = phx.webhooksEnv.GOOGLE_SERVICE_ACCOUNT_JSON
+
+  if (spreadsheetId === undefined || serviceAccount === undefined) {
+    return null
+  }
+
+  return {
+    type: 'EditGoogleSpreadsheet',
+    spreadsheetId,
+    credentials: JSON.parse(serviceAccount),
+    edits: [
+      {
+        ranges: {
+          'Orders!A:C': [
+            [data.configurationId, 'Custom Chair', { type: 'ConfigurationLink', name: resources.ownerLink }],
+          ],
+        },
+        mode: 'append',
       },
-      mode: 'append',
-    },
-    {
-      ranges: {
-        'Summary!B5': [[new Date().toLocaleString('en-GB')]],
+      {
+        ranges: {
+          'Summary!B5': [[new Date().toLocaleString('en-GB')]],
+        },
+        mode: 'overwrite',
       },
-      mode: 'overwrite',
-    },
-  ],
-}
+    ],
+  }
+})
 ```
 
 ### Callback Hook / Result
 
-Sometimes, the provided tasks are not enough and you need to define a custom callback to be called after the tasks are executed. You can define a callback task in `phx.webhooks.finalizeHandlerBuilder` and even return a result to the client.
+Sometimes, the provided tasks are not enough and you need to define a custom callback to be called after the tasks are executed. Build it with `phx.webhooks.callbackBuilder`, register it with `withCallback` on `phx.webhooks.finalizeHandlerBuilder`, and even return a result to the client.
 This callback handler is meant to be used for custom integrations, sending data to 3rd party services, etc.
 
-The callback definition has two parts, first you define a `CallbackData` handler that maps the resources and state to the data that will be passed to the callback handler.
+The callback adds a `CallLambdaBack` task, which the platform runs after all other tasks; it then calls the webhook's callback operation with the data and resource links. The resource links it receives are signed and expire after 30 minutes. Only resources with an `s3Key` (generated PDFs, CSVs and images) and configuration links can be passed.
+
+The callback definition has two parts, first you define a `CallbackData` handler that maps the resources and task data to the data that will be passed to the callback handler.
 
 ```ts
 // src/webhooks/handlers/configurator-finalize-handler/tasks/callback-task.ts
 export const callbackTask = phx.webhooks.callbackBuilder
   // Task Data and Context is available
-  .withCallbackData((resources, state) => {
+  .withCallbackData((resources, data) => {
     return {
       // data that will be passed to the callback handler
       replayData: {
-        emailAddress: state.finalizeData.emailAddress,
+        emailAddress: data.finalizeData.emailAddress,
       },
       // generated resources that should be forwarded to the callback handler
       resources: {
@@ -859,7 +976,7 @@ The `FinalizeResult` returned from the callback handler is then passed back to t
 
 ## Admin Finalization
 
-Admin finalization is triggered when an admin publishes an AdminConfiguration. The Admin Finalization handler can publish a `PublishRevisionTask`, that maps `AdminConfiguration` to a public
+Admin finalization is triggered when an admin publishes from Project Admin. The SDK builds the Admin finalization handler automatically: `phx.webhooks` has no builder for it, and `src/webhooks/index.ts` registers nothing. Without chunks, it returns a `PublishRevision` task that maps the `AdminConfiguration` to a public
 `PublishedDataRevision` that is stored in the database and published to s3. Latest published revision link is stored in `SessionToken` and its data are fetched before initializing domain.
 
 When chunks are defined in the domain spec, the handler auto-detects them and maps the published data into per-chunk payloads. Current servers provide a pre-signed staging URL; the current SDK uploads all chunks there and returns the lightweight `PublishRevisionChunksStaged` task, keeping chunk data out of the Lambda response and Redis job payload. The server checks the staged object before downloading it: payloads up to **100 MiB** are accepted, while a larger payload fails publishing with an explicit size-limit error.
@@ -868,30 +985,32 @@ Compatibility is preserved during upgrades. An older SDK still returns the inlin
 
 No sensitive data should be exposed!
 
-The schema of the published data is defined in the `AdminData` type passed from domain and it is validated before initializing a domain.
+The published data is validated against the project's published data schema before a configurator initializes its domain with it.
 
-You can define the Admin Finalization handler in the following way.
+Presets, preset categories, recipes and swatch options are published without project code. To customise the published data, default-export a handler from a file in `src/handlers/`:
+
+- `phx.domain.admin.createMapPublishedRevisionDataHandler(({ entities, adminEntity }) => data)` - the published data of a project without chunks (the `PublishRevision` task)
+- `phx.domain.admin.createMapPublishedChunkedDataHandler(({ entities, adminEntity, connectedSheetData }) => chunks)` - per-chunk data of a project with chunks (the `PublishRevisionChunksStaged` task, or `PublishRevisionChunks` inline when the platform offers no staging upload)
+- `phx.domain.admin.createDataRowValidatorHandler` and `phx.domain.admin.createSheetValidatorHandler` - business rules for manual and connected data, checked again when publishing
 
 ```ts
-// src/webhooks/handlers/admin-finalize-handler.ts
-export const adminFinalizeHandler = phx.webhooks.adminFinalizeHandlerBuilder
-  .withPublishedRevision(entities => {
-    // validated configuration state is passed to the handler
-    return entities
-      .filter((e): e is AdminDomain.PresetCategory => AdminDomain.PresetCategory.is(e) && e.visible)
-      .sort((a, b) => a.index - b.index)
-      .map(category => {
-        // .. map the admin data to whatever the configurator needs
-      })
-  })
-  .build()
+// src/handlers/map-published-revision-data.ts
+export default phx.domain.admin.createMapPublishedRevisionDataHandler(({ entities }) => {
+  // validated admin entities are passed to the handler
+  return {
+    customMaterials: entities
+      .filter(phx.domain.admin.model.CustomMaterial.is)
+      .filter(material => material.visible)
+      .map(material => ({ id: material.id, name: material.name })),
+  }
+})
 ```
 
-Before the admin finalization handler is called, the `AdminConfiguration` data are first validated via the admin domain and its violations.
+Before the admin finalization runs, the `AdminConfiguration` data are first validated via the admin domain and its violations. See **[Publishing](?path=/docs/phoenix-publishing--docs)** for the mapping handlers and chunks, and **[Connected Data Sources](?path=/docs/phoenix-connected-data-sources--docs)** for `connectedSheetData` and the validators.
 
 ## Auth Hook
 
-Auth hook is triggered when a configurator session is created or refreshed and the deployment enables it. For legacy projects, set this in `spec/application.yaml`, then run `phoenix sync`:
+Auth hook is triggered when a configurator session is created or refreshed and the deployment enables it. Enable it in a spec file such as `spec/application.yaml` (add `useClerk: true` as well for Clerk sign-in), then run `phoenix sync`:
 
 ```yaml
 useAuthHook: true
@@ -900,32 +1019,36 @@ useAuthHook: true
 Auth hook can define different types of handlers.
 
 - For Clerk:
-  - CodeFlow Handler
-  - RefreshFlow Handler
+  - CodeFlow Handler (`withClerkCodeHandler`)
+  - Session Handler (`withClerkSessionHandler`), for the inline Clerk sign-in
+  - RefreshFlow Handler (`withClerkRefreshHandler`)
 - Custom handlers:
-  - CodeFlow Handler
-  - RefreshFlow Handler
-- AnonymousFlow Handler
+  - CodeFlow Handler (`withCodeHandler`)
+  - RefreshFlow Handler (`withRefreshHandler`)
+- AnonymousFlow Handler (`withAnonymousHandler`)
 
 ```ts
 // src/webhooks/handlers/auth-handler.ts
 export const authHandler = phx.webhooks.authHandlerBuilder
   // To enable default authentication method with Clerk:
   .withClerkCodeHandler()
+  .withClerkSessionHandler()
   .withClerkRefreshHandler()
 
   // To implement custom auth handlers.
   // For example to integrate with customer's auth.
   .withCodeHandler(async payload => {
-    // ... CodeFlow implementation
+    // ... CodeFlow implementation, see CodeFlow Handler below
+    return { success: false }
   })
   .withRefreshHandler(async payload => {
-    // .. RefreshFlow implementation
+    // .. RefreshFlow implementation, see RefreshFlow Handler below
+    return { success: false }
   })
 
   // Add to allow anonymous access.
   .withAnonymousHandler(async () => {
-    return { success: false }
+    return { success: true, data: {}, role: 'anonymous' }
   })
 
   // Assign chunk scopes for chunked published data access control.
@@ -940,6 +1063,8 @@ export const authHandler = phx.webhooks.authHandlerBuilder
 
 For full details on `withPublishedChunkScopes()`, scope resolver patterns, and chunked publishing, see **[Publishing - Access Control](?path=/docs/phoenix-publishing--docs#access-control)**.
 
+A handler answers `{ success: false }` to refuse the session, or `{ success: true, data, role, refreshToken?, expirationTime?, scopes?, userId? }` to grant it. `role` is `anonymous`, `user`, `admin` or `superadmin`. `expirationTime` is an absolute Unix timestamp in seconds, not a duration, and defaults to 3 hours from now; keep the default, which session tracking assumes, unless the client needs other session lengths. `data` is validated against the spec's `sessionData` schema, which may not declare required properties: Admin and preset sessions carry no custom session data.
+
 ### Clerk handlers
 
 For the optional inline Configurator and Admin UI that uses `withClerkSessionHandler()`, see [Clerk Sign-In](?path=/docs/phoenix-clerk-sign-in--docs).
@@ -967,31 +1092,15 @@ We get the rest of the Clerk ENVs after creating a new OAuth application in `[YO
 - `https://<your server>/deployments/auth/callback` for every server the configurator is deployed to
 - `http://localhost:3000/deployments/auth/callback` for local development
 
-Save the OAuth application, then copy these values to the webhook environment only:
+Save the OAuth application, then enter in the customer's **Clerk Settings** tab in Studio:
 
-```
-# Application credentials -> Client ID
-# Where to put it: webhook
-OAUTH_PROVIDER_CLIENT_ID=xxx
+- the client ID and client secret from **Application credentials**
+- the base URL, the origin part of the Discovery URL (`https://<your Clerk frontend API domain>/`)
+- a JWT secret for signing tokens: the base64 of a long random key
 
-# Application credentials -> Client Secret
-# Where to put it: webhook
-OAUTH_PROVIDER_CLIENT_SECRET=xxx
+The platform passes them to the webhook as the generated variables `OAUTH_PROVIDER_CLIENT_ID`, `OAUTH_PROVIDER_CLIENT_SECRET`, `OAUTH_PROVIDER_BASE_URL` and `JWT_SECRET_BASE64`, beside `CLERK_API_KEY`, `FRONTEND_URL` and `RESOURCES_URL`. The project declares none of them and keeps none of them in its `.env`.
 
-# Origin part of the Discovery URL
-# Where to put it: webhook
-OAUTH_PROVIDER_BASE_URL=https://<your Clerk frontend API domain>/
-```
-
-Save the same OAuth client ID, client secret, and base URL in the customer's **Clerk Settings** tab in Studio. The remaining webhook variable is not taken from Clerk:
-
-```
-# For signing tokens - generate reasonably long alphanumeric key
-# Where to put it: webhook
-JWT_SECRET_BASE64=<base64 of a long random key>
-```
-
-For a deployment, run `pnpm phoenix deployment:prepare` followed by `pnpm phoenix deployment:finish`. For local development, run `pnpm deployment:prepare-local`. These current commands use the customer settings stored in Studio; the removed `environment:create` and `deployment:register` commands are not part of the setup flow.
+Deploy with `pnpm phoenix deploy`; CI pipelines run `pnpm phoenix deployment:prepare` followed by `pnpm phoenix deployment:finish`. For local development, `phoenix dev` prepares its own development deployment. All of them use the customer settings stored in Studio.
 
 #### Clerk organization
 
@@ -1043,27 +1152,40 @@ CodeFlow solves the problem of safely passing credentials to the client from 3rd
 and receives a one time `code` in return. This code is then passed to the client in a query parameter and used to authenticate the session. The server after receiving
 the code, retrieves the passed credentials from temporary storage and calls the Auth Hook CodeFlow Handler. The handler is then responsible for authenticating the user and returning the session data.
 
+The code handler receives `{ type: 'code', accessToken, refreshToken?, idToken? }`.
+
 ```ts
-export const authHandler = phx.webhooks.authHandlerBuilder.withCodeHandler(async payload => {
+export const authHandler = phx.webhooks.authHandlerBuilder.withCodeHandler(async (payload, { logger }) => {
   // refresh token may or may not be present based on what the 3rd party service sends
   const { accessToken, refreshToken } = payload
 
-  // authenticate the user using the provided credentials, fetch user data, etc...
+  // authenticate the visitor using the provided credentials, fetch user data, etc...
+  const response = await fetch(`${phx.webhooksEnv.CRM_API_URL}/me`, {
+    headers: { authorization: `Bearer ${accessToken}` },
+  })
+
+  if (!response.ok) {
+    logger.warn(`The CRM refused the access token with status ${response.status}.`)
+    // refuse the session
+    return { success: false }
+  }
+
+  const { id: userId }: { readonly id: string } = await response.json()
 
   return {
-    // return true/false based on the authentication result, if error is returned, the webhook will return 500 and an error will be reported to the alerting system
+    // return true/false based on the authentication result, if the handler throws, the webhook will return 500 and an error will be reported to the alerting system
     success: true,
     data: {
-      // custom session data that will be stored in the session - defined via the SessionData type
+      // custom session data that will be stored in the session - defined via the sessionData schema
     },
-    // role of the user, can be 'admin','user' or 'anonymous'
+    // role of the session, can be 'superadmin', 'admin', 'user' or 'anonymous'
     role: 'user',
     // id of the signed-in user in your system; the session token's `sub` becomes `custom-<userId>`
     userId,
     // refresh token that will be passed to the refresh flow when the session expires
     refreshToken,
-    // expiration time of the session in seconds
-    expirationTime,
+    // optional expirationTime: an absolute Unix timestamp in seconds, not a duration. Keep the 3-hour default,
+    // which session tracking assumes, unless the client needs other session lengths
   }
 })
 ```
@@ -1072,7 +1194,7 @@ export const authHandler = phx.webhooks.authHandlerBuilder.withCodeHandler(async
 
 #### RefreshFlow Handler
 
-RefreshFlow is triggered when the session is authenticated via `refreshToken`. The handler is responsible for refreshing the session data and returning the new session data.
+RefreshFlow is triggered when the session is authenticated via `refreshToken`. The handler is responsible for refreshing the session data and returning the new session data. It receives `{ type: 'refresh', refreshToken }`.
 
 ```ts
 export const authHandler = phx.webhooks.authHandlerBuilder.withRefreshHandler(async payload => {
@@ -1080,21 +1202,32 @@ export const authHandler = phx.webhooks.authHandlerBuilder.withRefreshHandler(as
   const { refreshToken } = payload
 
   // Use the refresh token to refresh the session data, fetch user data, etc...
+  const response = await fetch(`${phx.webhooksEnv.CRM_API_URL}/token/refresh`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ refreshToken }),
+  })
+
+  if (!response.ok) {
+    return { success: false }
+  }
+
+  const refreshed: { readonly userId: string; readonly refreshToken: string } = await response.json()
 
   return {
-    // return true/false based on the authentication result, if error is returned, the webhook will return 500 and an error will be reported to the alerting system
+    // return true/false based on the authentication result, if the handler throws, the webhook will return 500 and an error will be reported to the alerting system
     success: true,
     data: {
-      // custom session data that will be stored in the session - defined via the SessionData type
+      // custom session data that will be stored in the session - defined via the sessionData schema
     },
-    // role of the user, can be 'admin','user' or 'anonymous'
+    // role of the session, can be 'superadmin', 'admin', 'user' or 'anonymous'
     role: 'user',
     // return the user id again: a refresh without it turns the session into the browser's anonymous user
-    userId,
+    userId: refreshed.userId,
     // refresh token that will be passed to the refresh flow when the session expires
-    refreshToken,
-    // expiration time of the session in seconds
-    expirationTime,
+    refreshToken: refreshed.refreshToken,
+    // optional expirationTime: an absolute Unix timestamp in seconds, not a duration. Keep the 3-hour default,
+    // which session tracking assumes, unless the client needs other session lengths
   }
 })
 ```
@@ -1110,17 +1243,15 @@ export const authHandler = phx.webhooks.authHandlerBuilder
     // Do whatever you need to here, but it is probably not a good idea
 
     return {
-      // return true/false based on the authentication result, if error is returned, the webhook will return 500 and an error will be reported to the alerting system
+      // return true/false based on the authentication result, if the handler throws, the webhook will return 500 and an error will be reported to the alerting system
       success: true,
       data: {
-        // custom session data that will be stored in the session - defined via the SessionData type
+        // custom session data that will be stored in the session - defined via the sessionData schema
       },
-      // role of the user, can be 'admin','user' or 'anonymous'
+      // role of the session, can be 'superadmin', 'admin', 'user' or 'anonymous'
       role: 'anonymous',
-      // refresh token that will be passed to the refresh flow when the session expires
-      refreshToken,
-      // expiration time of the session in seconds
-      expirationTime,
+      // optional: absolute Unix timestamp in seconds, not a duration; defaults to 3 hours from now
+      expirationTime: Math.floor(Date.now() / 1000) + 3 * 60 * 60,
     }
   })
 ```
@@ -1185,35 +1316,31 @@ export const configuratorFinalizeHandler = phx.webhooks.finalizeHandlerBuilder
 
 The data returned by your prefetch handler is available to all subsequent tasks as `prefetchedData`:
 
-```ts
+```tsx
 // Tasks can access prefetched data
 export const pdfTask = phx.webhooks.taskFactory.createGeneratePdfTask((resources, data, ctx) => {
   // Access prefetched data
   const { totalPrice, estimatedDeliveryDate, productCatalog } = data.prefetchedData
 
-  return {
-    type: 'GeneratePdf',
-    name: resources.configurationPdf,
-    html: {
-      template: `
-        <h1>Configuration Summary</h1>
-        <p>Total Price: ${'{{'}totalPrice{{"}}"}}</p>
-        <p>Estimated Delivery: ${'{{'}deliveryDate{{"}}"}}</p>
-        <ul>
-          ${'{{'}#each products${'}}'}
-            <li>${'{{'}this.name${'}}'}  - ${'{{'}this.sku{{"}}"}}</li>
-          ${'{{'}/each${'}}'}
-        </ul>
-      `,
-      data: {
-        totalPrice,
-        deliveryDate: estimatedDeliveryDate,
-        products: productCatalog.items,
-      },
-      includeResources: [],
-    },
-    // ... rest of PDF configuration
-  }
+  return ctx.pdfTaskBuilder
+    .withResourceName(resources.configurationPdf)
+    .withReactBody(
+      <html>
+        <body>
+          <h1>Configuration Summary</h1>
+          <p>Total Price: {totalPrice}</p>
+          <p>Estimated Delivery: {estimatedDeliveryDate}</p>
+          <ul>
+            {productCatalog.items.map(item => (
+              <li key={item.sku}>
+                {item.name} - {item.sku}
+              </li>
+            ))}
+          </ul>
+        </body>
+      </html>
+    )
+    .build()
 })
 ```
 
@@ -1245,39 +1372,38 @@ export interface PrefetchTaskData<
 
 ## Dynamic Resources Factory
 
-The Dynamic Resources Factory allows you to create resources dynamically at runtime based on configuration state, user data, or other conditions. Unlike static resource definitions in the domain, dynamic resources are generated programmatically during finalization.
+The Dynamic Resources Factory allows you to create resources dynamically at runtime based on configuration state, finalize data, or other conditions. Unlike static resource definitions in the spec, dynamic resources are generated programmatically during finalization.
 
 Its handler context exposes the same request-bound `ctx.resolveLocalizable(value)` and raw `ctx.i18n` as task handlers.
 
-**Important**: Dynamic resource names are not statically typed since they are created at runtime. You'll need to reference them by string names in templates and tasks.
+**Important**: Dynamic resource names are not statically typed since they are created at runtime, and they are not part of the `resources` map tasks receive. You'll need to reference them by string names in templates and tasks.
 
 ### Available Resource Creation Methods
 
 The `phx.webhooks.dynamicResourcesFactory` provides methods for creating different types of resources:
 
 ```ts
-// src/webhooks/handlers/dynamic-resources.ts
+// src/webhooks/handlers/configurator-finalize-handler/tasks/dynamic-resources.ts
 
-// Server-generated images
-const generatedImageHandler = phx.webhooks.dynamicResourcesFactory.createGeneratedImage((resources, data, ctx) => {
+// Server-generated images, produced by a GenerateImages task under the same name
+export const generatedImageHandler = phx.webhooks.dynamicResourcesFactory.createGeneratedImage((resources, data) => {
   return {
-    type: 'GeneratedImage',
+    type: 'Image',
     name: 'dynamicServerImage',
     s3Key: `generated/${data.configurationId}/render.png`,
   }
 })
 
-// Dynamic links
-const linkHandler = phx.webhooks.dynamicResourcesFactory.createLink((resources, data, ctx) => {
+// Dynamic configuration links, produced by a GenerateConfigurationLink task under the same name
+export const linkHandler = phx.webhooks.dynamicResourcesFactory.createLink(() => {
   return {
-    type: 'Link',
+    type: 'ConfigurationLink',
     name: 'customShareLink',
-    url: `${data.frontendUrl}/share/${data.configurationId}?utm_source=dynamic`,
   }
 })
 
-// Dynamic PDFs
-const pdfHandler = phx.webhooks.dynamicResourcesFactory.createPdf((resources, data, ctx) => {
+// Dynamic PDFs, produced by a PDF task under the same name
+export const pdfHandler = phx.webhooks.dynamicResourcesFactory.createPdf((resources, data) => {
   return {
     type: 'Pdf',
     name: 'dynamicReport',
@@ -1286,7 +1412,21 @@ const pdfHandler = phx.webhooks.dynamicResourcesFactory.createPdf((resources, da
 })
 ```
 
-Other available methods include: `createClientGeneratedImage`, `createExistingImage`, `createCsv`, and `createResource`.
+Other available methods include: `createClientGeneratedImage` (`{ type: 'Image', name, clientGenerated: true, s3Key }`), `createExistingImage` (`{ type: 'Image', name, exists: true, url }`), `createCsv` (`{ type: 'Csv', name, s3Key? }`), and `createResource` (any of these). `getClientSideImageResourceName(entityId, instanceName)` returns the name of a configurator-rendered image resource.
+
+### Registering dynamic resources
+
+A dynamic resource takes effect only when its handler is registered with `withResources` on the finalization handler, one call per handler:
+
+```ts
+// src/webhooks/handlers/configurator-finalize-handler/configurator-finalize-handler.ts
+export const configuratorFinalizeHandler = phx.webhooks.finalizeHandlerBuilder
+  .withResources(generatedImageHandler)
+  .withResources(pdfHandler)
+  .withTask(dynamicImageTask)
+  .withTask(dynamicReportTask)
+  .build()
+```
 
 ### Conditional Resource Creation
 
@@ -1303,7 +1443,7 @@ const conditionalImageHandler = phx.webhooks.dynamicResourcesFactory.createGener
   }
 
   return {
-    type: 'GeneratedImage',
+    type: 'Image',
     name: 'customMaterialPreview',
     s3Key: `previews/${data.configurationId}/custom-materials.png`,
   }
@@ -1319,7 +1459,7 @@ const multipleImagesHandler = phx.webhooks.dynamicResourcesFactory.createGenerat
   const colorOptions = data.finalizeData.requestedColors || []
 
   return colorOptions.map((color, index) => ({
-    type: 'GeneratedImage',
+    type: 'Image',
     name: `colorPreview${index}`,
     s3Key: `colors/${data.configurationId}/${color}.png`,
   }))
@@ -1328,58 +1468,77 @@ const multipleImagesHandler = phx.webhooks.dynamicResourcesFactory.createGenerat
 
 ### Using Dynamic Resources in Tasks
 
-Dynamic resources are automatically available to finalization tasks:
+Registered dynamic resources are available to finalization tasks by name. A `GenerateImages` task renders the dynamic image, and a PDF built with `pdfTaskBuilder` embeds it and is stored as the dynamic PDF:
+
+```tsx
+// src/webhooks/handlers/configurator-finalize-handler/tasks/dynamic-tasks.tsx
+import { ResourceHelpers } from '@salsita-ai/sdk/webhook'
+
+export const dynamicImageTask = phx.webhooks.taskFactory.createGenerateImagesTask((_resources, data, ctx) => {
+  const imageConfig = ctx.blenderProjections.getBlenderImageConfig(data.state, 'Default', data.state.rootEntityId, {
+    width: 1920,
+    height: 1080,
+  })
 
-```ts
-export const emailTask = phx.webhooks.taskFactory.createSendEmailTask((resources, data) => {
   return {
-    type: 'SendEmail',
-    from: 'noreply@example.com',
-    to: data.finalizeData.emailAddress,
-    subject: 'Your Configuration',
-    html: {
-      template: '<img src="${"{{"}resource-dynamicServerImage{{"}}"}}" />',
-      data: {},
-      includeResources: [
-        {
-          name: 'dynamicServerImage', // Reference dynamic resource
-          type: 'Image',
-          embeddingType: 'Embedded',
-        },
-      ],
-    },
-    attachments: [],
+    type: 'GenerateImages',
+    deploymentId: data.deploymentId,
+    blenderSetupTemplate: 'template.blend',
+    templateFiles: ['LaProvencal.gltf'],
+    images: [{ name: 'dynamicServerImage', fileFormat: 'PNG', ...imageConfig }],
   }
 })
+
+export const dynamicReportTask = phx.webhooks.taskFactory.createGeneratePdfTask((_resources, _data, ctx) => {
+  return ctx.pdfTaskBuilder
+    .withResourceName('dynamicReport')
+    .withIncludedResources({
+      // Reference the dynamic resource by its name
+      other: [{ name: 'dynamicServerImage', type: 'Image', embeddingType: 'Embedded' }],
+    })
+    .withReactBody(
+      <html>
+        <body>
+          <ResourceHelpers.Image resource="dynamicServerImage" alt="Your configuration" />
+        </body>
+      </html>
+    )
+    .build()
+})
 ```
 
 ## Backend Data Handler
 
 The Backend Data Handler allows you to fetch data on the server that will be automatically made available both in the domain (client-side) and in webhook contexts. Its main purpose is to securely fetch data using API keys or other sensitive credentials that cannot be exposed to the client, while making that data available throughout your application.
 
+Responses of at least 32 KiB are automatically gzip-compressed when the caller accepts gzip and the base64 representation is smaller. Project handlers return the same `backendData` object; the API and configurator receive decoded JSON. This also works through `phoenix dev` when both the server and CLI support gzip. Older tunnel clients keep plain JSON.
+
+Compression does not remove platform limits: the complete encoded development-tunnel request must fit within 5 MiB, and deployed webhooks remain subject to Lambda's buffered response limit. The tunnel accepts up to 100 MiB of decoded gzip data. Data that does not compress enough must be reduced or split. Binary responses appear as a byte-count placeholder in the development tunnel inspector.
+
+The configurator requests backend data in the browser, and the webhook runs the handler again before every configurator finalization, so tasks get their own fresh `backendData`. A failure in the browser only leaves `backendData` undefined; a failure before a finalization fails the finalization.
+
 ### Defining a Backend Data Handler
 
-Backend data handlers are defined inline in the webhook builder:
+Backend data handlers are defined inline in the webhook builder. The handler returns `{ backendData }`:
 
 ```ts
 // src/webhooks/index.ts
 export default phx.webhooks.webhookBuilder
   .withAuthHook(authHandler)
   .withConfiguratorFinalize(configuratorFinalizeHandler)
-  .withFetchBackendData(async ({ frontendData, sessionPayload, deploymentId }, { logger }) => {
+  .withFetchBackendData(async ({ sessionPayload }, { logger }) => {
     logger.info('Fetching backend data')
 
-    // Fetch data using API keys not exposed to client
-    const userProfile = await fetch('https://api.example.com/users/' + sessionPayload.userId, {
-      headers: { Authorization: `Bearer ${phx.webhooksEnv.API_KEY}` },
-    }).then(res => res.json())
-
-    const pricingData = await fetchPricingData(deploymentId, phx.webhooksEnv.PRICING_API_KEY)
+    // Fetch with an API key the browser never sees; customerId is a field of the spec's sessionData
+    const response = await fetch(`${phx.webhooksEnv.PRICING_API_URL}/customers/${sessionPayload.customerId}`, {
+      headers: { Authorization: `Bearer ${phx.webhooksEnv.PRICING_API_KEY}` },
+    })
+    const customer: { readonly tier: string; readonly basePrice: number } = await response.json()
 
     return {
       backendData: {
-        userProfile,
-        pricingData,
+        tier: customer.tier,
+        basePrice: customer.basePrice,
         fetchedAt: new Date().toISOString(),
       },
     }
@@ -1396,12 +1555,14 @@ Define the schema for backend data in `spec/application.yaml`:
 backendData:
   type: object
   properties:
-    exchangeRateAtStartTime:
+    tier:
+      type: string
+    basePrice:
       type: number
-    userProfile:
-      type: object
+    fetchedAt:
+      type: string
   required:
-    - exchangeRateAtStartTime
+    - fetchedAt
   additionalProperties: false
 ```
 
@@ -1411,46 +1572,31 @@ Backend data is automatically fetched and made available throughout your applica
 
 **In the Domain (Client-side)**: The data is automatically available in the domain context and can be used in expressions, components, and UI logic.
 
-**In Webhooks**: Backend data is available to prefetch handlers and finalization tasks:
+**In Webhooks**: Backend data is available to prefetch handlers and finalization tasks as `data.backendData`. Like `ctx.backendData` in expressions, it is `Record<string, unknown> | undefined`: the schema validates the handler's answer but does not type what reads it, so narrow each value before use:
 
-```ts
+```tsx
 // Prefetch handlers receive backend data
 export const prefetchHandler = phx.webhooks.prefetchBuilder
-  .withPrefetchHandler(async (data, ctx) => {
-    const { userProfile, pricingData } = data.backendData || {}
-
-    // Use backend data to prepare additional information
-    const discountRate = userProfile?.tier === 'premium' ? 0.15 : 0.05
-    const finalPrice = pricingData?.basePrice * (1 - discountRate)
-
-    // Fetch additional data based on user profile
-    const recommendedProducts = await fetchRecommendedProducts(userProfile?.preferences)
+  .withPrefetchHandler(data => {
+    const tier = data.backendData?.['tier']
+    const basePrice = data.backendData?.['basePrice']
+    const discountRate = tier === 'premium' ? 0.15 : 0.05
 
     return {
       discountRate,
-      finalPrice,
-      recommendedProducts,
-      userTier: userProfile?.tier,
+      finalPrice: typeof basePrice === 'number' ? basePrice * (1 - discountRate) : null,
     }
   })
   .build()
 
 // Tasks also receive backend data
 export const pricingTask = phx.webhooks.taskFactory.createGeneratePdfTask((resources, data, ctx) => {
-  const { pricingData } = data.backendData || {}
+  const basePrice = data.backendData?.['basePrice']
 
-  return {
-    type: 'GeneratePdf',
-    name: resources.pricingReport,
-    html: {
-      template: '<h1>Price: ${"{{"}price{{"}}"}}</h1>',
-      data: {
-        price: pricingData?.totalPrice || 'N/A',
-      },
-      includeResources: [],
-    },
-    // ... rest of PDF configuration
-  }
+  return ctx.pdfTaskBuilder
+    .withResourceName(resources.pricingReport)
+    .withReactBody(<h1>Price: {typeof basePrice === 'number' ? basePrice.toFixed(2) : 'N/A'}</h1>)
+    .build()
 })
 ```
 
@@ -1465,13 +1611,16 @@ export interface FetchBackendDataPayload<
 > {
   deploymentId: DeploymentId
   frontendUrl: FrontendUrl
-  frontendData: FRONTEND_DATA
+  frontendData?: FRONTEND_DATA
   sessionRole: SessionRole
   sessionPayload: SESSION_DATA
-  publishedAdminRevisionPath: string | undefined
+  publishedAdminRevisionPath?: string
+  publishedChunkUrls?: Record<string, string>
 }
 ```
 
+The `backendData` the handler returns is validated against the `backendData` schema.
+
 ### Use Cases
 
 Backend data handlers are ideal when you need to:
@@ -1509,11 +1658,11 @@ In this guide, we explored Phoenix's webhook system:
 - **Webhook-based architecture** enables server-side processing for authentication, finalization, and admin workflows
 - **Domain-aware builders** provide type-safe webhook development with full access to domain context
 - **Environment variables** allow secure configuration management for API keys and external service credentials
-- **Task execution pipeline** processes resources sequentially to enable resource reuse and dependency management
+- **Task execution pipeline** runs tasks by type, so links and rendered images are ready before the PDFs, emails and callback that use them
 - **Resource system** manages static domain resources and dynamic runtime-generated resources
 - **React templates** render PDF and email bodies as `.tsx` trees via builder chains, with Handlebars retained as legacy
 - **Authentication hooks** support custom auth flows, Clerk integration, and anonymous access patterns
-- **Admin finalization** transforms admin configurations into published data for configurators
+- **Admin finalization**, built by the SDK and customised with handlers, transforms admin configurations into published data for configurators
 
 **Advanced Features:**