@salsita-ai/sdk 0.0.0-stage → 0.49.0-develop.2a2e8d75e7

package/dist/docs/phoenix/webhooks.mdx

@@ -0,0 +1,1536 @@
+# Webhooks
+
+- [Webhook builders](#webhook-builders)
+- [Environment variables](#environment-variables)
+- [Configurator Finalization](#configurator-finalization)
+- [Admin Finalization](#admin-finalization)
+- [Auth Hook](#auth-hook)
+- [Advanced Features](#advanced-features)
+  - [Prefetch Tasks](#prefetch-tasks)
+  - [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.
+
+- Configurator Finalization
+- Admin Finalization
+- Auth Hook
+
+## 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.
+
+**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.taskFactory` - Factory for creating finalization tasks
+- `phx.webhooks.callbackBuilder` - Builder for callback handlers
+- `phx.webhooks.prefetchBuilder` - Builder for prefetch handlers
+- `phx.webhooks.dynamicResourcesFactory` - Factory for dynamic resource creation
+
+### Webhook Entry Point
+
+```ts
+// src/webhooks/index.ts
+import { authHandler } from './handlers/auth-handler.js'
+import { configuratorFinalizeHandler } from './handlers/configurator-finalize-handler/configurator-finalize-handler.js'
+
+export default phx.webhooks.webhookBuilder
+  .withAuthHook(authHandler)
+  .withConfiguratorFinalize(configuratorFinalizeHandler)
+  .withFetchBackendData(async ({ frontendData }, { logger }) => {
+    logger.info('Fetching backend data')
+    return {
+      backendData: {
+        // Server-side data fetched with API keys
+      },
+    }
+  })
+  .build()
+```
+
+## Environment variables
+
+Environment variables for webhooks are defined in `spec/application.yaml` under the `env.webhook` section.
+
+### Defining Environment Variables
+
+```yaml
+# spec/application.yaml
+env:
+  webhook:
+    EMAIL_TO:
+      type: email
+    EMAIL_FROM:
+      type: email
+    GOOGLE_SPREADSHEET_ID:
+      type: str
+    GOOGLE_SERVICE_ACCOUNT_KEY:
+      type: str
+```
+
+### Using Environment Variables
+
+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
+```
+
+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.
+
+## Configurator Finalization
+
+Configurator finalization is triggered when a configuration is being finalized. It enables the developer to declare a set of tasks to be executed by the server/workers, define a callback and possibly return a result to the client.
+
+To construct a configurator finalization handler, you can use `phx.webhooks.finalizeHandlerBuilder` to add tasks and a possible callback. You can also use [prefetch tasks](#prefetch-tasks) for early setup and [backend data handlers](#backend-data-handler) for server-side data fetching.
+
+```ts
+// src/webhooks/handlers/configurator-finalize-handler/configurator-finalize-handler.ts
+import { callbackTask } from './tasks/callback-task.js'
+import { simpleCsvTask } from './tasks/csv-task.js'
+import { simpleEmailTask } from './tasks/email-task.js'
+import { simpleImageTask } from './tasks/generate-images-task.js'
+import { linkTasks } from './tasks/link-tasks.js'
+import { simplePdfTask } from './tasks/pdf-task.js'
+import { prefetchHandler } from './tasks/prefetch-handler.js'
+
+export const configuratorFinalizeHandler = phx.webhooks.finalizeHandlerBuilder
+  .withPrefetch(prefetchHandler) // Optional: early validation and setup
+  .withTask(linkTasks)
+  .withTask(simplePdfTask)
+  .withTask(simpleCsvTask)
+  .withTask(simpleEmailTask)
+  .withTask(simpleImageTask)
+  .withCallback(callbackTask) // Optional: custom result processing
+  .build()
+```
+
+#### Resources
+
+Important concept for task definition are resources. They represent available data/documents that are either generated or provided to the tasks and can be referenced across the workflow.
+Each resource has a unique name and a type that defines it.
+
+Resources can be defined statically in `spec/application.yaml` or dynamically at runtime using the [Dynamic Resources Factory](#dynamic-resources-factory).
+
+**Static resources** are defined in `spec/application.yaml`:
+
+```yaml
+# spec/application.yaml
+resources:
+  - type: ConfigurationLink
+    name: ownerLink
+  - type: ConfigurationLink
+    name: readLink
+  - type: ConfigurationLink
+    name: readRevisionLink
+  - type: Pdf
+    name: simplePdf
+    s3Key: simplePdf
+  - type: Csv
+    name: simpleCsv
+    s3Key: simpleCsv
+  # Server-generated image
+  - type: Image
+    name: simpleImage
+    s3Key: someImageKey
+  # Client-generated image (uploaded from frontend)
+  - type: Image
+    name: clientImage
+    clientGenerated: true
+    s3Key: clientImage
+```
+
+These resources are automatically made available as typed properties in task handlers via the `resources` parameter.
+
+#### Task Payload
+
+Every task can use a payload that is passed to the task handler to define a task to be executed. Payload includes the available resources,
+configuration and deployment details, validated configuration entities and `FinalizeData` passed from client (defined and its schema parsed via `FinalizeData` type).
+
+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.
+
+#### Task Context
+
+Besides the payload, the task handler can also use the task context to access domain services to work with the data.
+
+Following services can be used to work with domain expressions, read components, translate texts, get rendered tree, etc.
+
+```ts
+export interface TaskContext<
+  ENTITIES extends DomainEntity<string>,
+  $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>,
+  ALLOWED_ROOT_ENTITIES extends ENTITIES,
+> {
+  logger: Logger
+  domain: Domain<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP>
+  componentReader: ComponentReader<ENTITIES>
+  validationProjections: ValidationProjections<ENTITIES, $MAP>
+  compositionProjections: CompositionProjections<ENTITIES, ALLOWED_ROOT_ENTITIES>
+  blenderProjections: BlenderProjections<ENTITIES>
+  i18n: I18n
+  resolveLocalizable: RuntimeResolveLocalizable
+  getPublicAssetUrl: (path: string) => string
+  emailTaskBuilder: EmailTaskBuilder
+  pdfTaskBuilder: PdfTaskBuilder
+}
+```
+
+#### 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.
+
+### Task execution order
+
+The webhook finalization follows a specific execution order to ensure proper data flow and resource availability:
+
+1. **Backend Data Handler** (if configured) - Fetches server-side data
+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
+
+### GenerateConfigurationLink Task
+
+This task generates a share link and is performed during server step. A single task can return multiple link configurations.
+
+Following example shows a task that generates multiple share links:
+
+```ts
+// src/webhooks/handlers/configurator-finalize-handler/tasks/link-tasks.ts
+export const linkTasks = phx.webhooks.taskFactory.createGenerateConfigurationLinkTask((resources, data) => {
+  const { configurationId, frontendUrl, revisionId } = data
+
+  return [
+    {
+      type: 'GenerateConfigurationLink',
+      name: resources.ownerLink,
+      frontendUrl,
+      configurationId,
+      access: 'o',
+    },
+    {
+      type: 'GenerateConfigurationLink',
+      name: resources.readLink,
+      frontendUrl,
+      configurationId,
+      revisionId,
+      expiration: 240,
+      access: 'r',
+    },
+    {
+      type: 'GenerateConfigurationLink',
+      name: resources.readRevisionLink,
+      frontendUrl,
+      configurationId,
+      revisionId,
+      expiration: 240,
+      access: 'rr',
+    },
+  ]
+})
+```
+
+Full definition of the task is defined in the `GenerateConfigurationLinkTask` type.
+
+```ts
+export interface GenerateConfigurationLinkTask {
+  type: typeof TaskType.GenerateConfigurationLink
+  /**
+   * The name of the resource to be generated
+   */
+  name: string
+  /**
+   * The URL where the frontend is hosted
+   */
+  frontendUrl: FrontendUrl
+  /**
+   * Expiration time of the generated link in hours, if not provided the link will not expire. Relevant only for revision links as owner links are always permanent.
+   */
+  expiration?: number
+  /**
+   * The access level of the generated link
+   */
+  access: AccessLevel
+  /**
+   * The ID of the configuration to generate the link for
+   */
+  configurationId: ConfigurationId
+  /**
+   * The ID of the revision to generate the link for in the case of a revision link
+   */
+  revisionId?: RevisionId
+}
+```
+
+### GenerateImages Task
+
+Generates images from the submitted configuration with headless Blender on the rendering worker. A default Python script drives the render, or a custom script uploaded to the private deployment assets can replace it. Templates, glTF files, textures, and HDRIs are cached on the worker so repeat jobs start faster.
+
+Use `ctx.blenderProjections.getBlenderImageConfig` to project output dimensions, entities, lights, and a generated camera from the same export-transformed state. For a custom camera or to use the template camera, use `getBlenderSceneConfig` instead, or assemble the payload from the [lower-level projections](?path=/docs/phoenix-blender-rendering--docs#lower-level-projections). Render pipeline options (`renderSettings`) and extended camera fields (depth of field, sensor size, clip planes) are optional and are set on the task in your factory.
+
+```ts
+// src/webhooks/handlers/configurator-finalize-handler/tasks/generate-images-task.ts
+export const simpleImageTask = phx.webhooks.taskFactory.createGenerateImagesTask((resources, data, ctx) => {
+  const imageSize = { width: 1920, height: 1080 }
+  const imageConfig = ctx.blenderProjections.getBlenderImageConfig(
+    data.state,
+    'Default',
+    data.state.rootEntityId,
+    imageSize
+  )
+
+  return {
+    type: 'GenerateImages',
+    deploymentId: data.deploymentId,
+    blenderSetupTemplate: 'template.blend',
+    templateFiles: ['LaProvencal.gltf'],
+    renderSettings: {
+      samples: 128,
+      viewTransform: 'Filmic',
+    },
+    images: [
+      {
+        name: resources.simpleImage,
+        fileFormat: 'PNG',
+        ...imageConfig,
+      },
+    ],
+  }
+})
+```
+
+The full payload shape and its validation live in the `GenerateImagesTask` type from `@salsita-ai/sdk/contracts/webhook`. Material overrides (including texture maps and transparency), lights, template or explicit cameras, render settings, asset paths, export-state authoring, and worker failure behavior are described in **[Blender Rendering](?path=/docs/phoenix-blender-rendering--docs)**.
+
+### GenerateCsv Task
+
+This task generates a CSV file from the provided data.
+
+```ts
+// src/webhooks/handlers/configurator-finalize-handler/tasks/csv-task.ts
+export const simpleCsvTask = phx.webhooks.taskFactory.createGenerateCsvTask((_, data, ctx) => {
+  const $root = ctx.domain.getRoot$Entity(data.state)
+
+  return {
+    type: 'GenerateCsv',
+    name: 'simpleCsv',
+    columns: $root.$csvColumns,
+    data: $root.$csvData,
+    header: true,
+  }
+})
+```
+
+Full definition of the task is defined in the `GenerateCsvTask` type.
+
+```ts
+export interface GenerateCsvTask {
+  type: typeof TaskType.GenerateCsv
+  /**
+   * The name of the csv file
+   */
+  name: string
+  /**
+   * The columns of the csv file
+   */
+  columns: string[]
+  /**
+   * The data to be written to the csv file
+   */
+  data: unknown[]
+  /**
+   * Prepend the byte order mark (BOM) to the output stream.
+   */
+  bom?: boolean | undefined
+  /**
+   * Set the field delimiter, one character only, defaults to a comma.
+   */
+  delimiter?: string
+  /**
+   * Display the column names on the first line if the columns option is provided or discovered.
+   */
+  header?: boolean
+}
+```
+
+### React templates: shared concepts
+
+The `GenerateStaticPdf` and `SendStaticEmail` tasks both render React trees to HTML via builders on the task context (`ctx.pdfTaskBuilder`, `ctx.emailTaskBuilder`). Handlers stay in `.tsx` and pass props (assets, domain values, etc.) into separate template components.
+
+#### Translations
+
+Task handlers and templates localize content using lingui — the same toolchain as the frontend. `ctx.resolveLocalizable(value)` is pre-bound to the request locale and the domain's `textLanguages` fallback chain. Builders use the same resolver for every `Localizable` input (`withSubject`, attachment `filename`, header/footer, body, and watermark text). Raw `ctx.i18n` remains available for direct Lingui APIs.
+
+In handler code, use the `msg` template tag:
+
+```tsx
+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 { HtmlHelpers } from '@salsita-ai/sdk/webhook'
+
+const EmailTemplate = ({ $root }: { $root: Phx['EnhancedModel']['$RootEntity'] }) => (
+  <div>
+    <h1>
+      <Trans>Your configuration</Trans>
+    </h1>
+    <p>
+      <HtmlHelpers.Localized>{$root.$pdfTitle}</HtmlHelpers.Localized>
+    </p>
+  </div>
+)
+```
+
+To render in a locale other than the request locale, chain `.withLocale('de')` early — subject, body, header/footer and attachment filenames all resolve against the chosen locale.
+
+#### Public asset URLs
+
+Place fonts, logos and other public files in `/assets/public`. Handlers resolve them via `ctx.getPublicAssetUrl()` and pass URLs through as props:
+
+```tsx
+ctx.pdfTaskBuilder.withReactBody(<PdfTemplate logoUrl={ctx.getPublicAssetUrl('logo.png')} />)
+```
+
+Private assets (Blender files, scripts) live in `/assets/private` — see [Static assets](#static-assets).
+
+#### Client-side images
+
+For embedding configurator-rendered images (from the `clientSideImage` component) in PDF bodies, email bodies, or as email attachments, see **[Client Side Rendering — using rendered images in webhooks](?path=/docs/other-features-client-side-rendering-declarative--docs#using-rendered-images-in-webhooks)**.
+
+### GenerateStaticPdf Task
+
+Generates a PDF via PdfShift, rendering React templates to HTML. Header, body and footer are each defined as React components (or plain HTML strings) and assembled with the `pdfTaskBuilder` exposed on `ctx`.
+The 'Static' in the task name refers to the fact that the PDF is generated statically, meaning that the PDF is generated in the webhook handler and there is no Handlebars template resolution on the server,
+except for resource reference interpolation and PdfShift variables.
+
+#### Quick example
+
+The handler is a `.tsx` file that returns the built task:
+
+```tsx
+// src/webhooks/handlers/configurator-finalize-handler/tasks/pdf-task.tsx
+import { PdfBody, PdfFooter, PdfHeader } from './pdf-template.js'
+
+export const simplePdfTask = phx.webhooks.taskFactory.createGeneratePdfTask((resources, data, ctx) => {
+  const $root = ctx.domain.getRoot$Entity(data.state)
+
+  return ctx.pdfTaskBuilder
+    .withResourceName(resources.simplePdf)
+    .withIncludedResources({
+      other: [{ name: resources.readRevisionLink, type: 'ConfigurationLink' }],
+    })
+    .withReactHeader(<PdfHeader />, { height: '30mm', startAt: 1 })
+    .withReactBody(<PdfBody $root={$root} logoUrl={ctx.getPublicAssetUrl('logo.png')} />)
+    .withReactFooter(<PdfFooter />, { height: '20mm', startAt: 1 })
+    .build()
+})
+```
+
+The template file:
+
+```tsx
+// src/webhooks/handlers/configurator-finalize-handler/tasks/pdf-template.tsx
+import { Trans } from '@lingui/macro'
+
+import { HtmlHelpers, PdfHelpers, ResourceHelpers } from '@salsita-ai/sdk/webhook'
+
+const pdfStyle = `
+  body { font-family: sans-serif; color: #2b2d30; margin: 20px; }
+  .summary { padding: 15px; background: #f3f3f3; border-left: 5px solid #888; }
+`
+
+export const PdfBody = ({ $root, logoUrl }: { $root: Phx['EnhancedModel']['$RootEntity']; logoUrl: string }) => (
+  <html>
+    <head>
+      <HtmlHelpers.Style>{pdfStyle}</HtmlHelpers.Style>
+    </head>
+    <body>
+      <img src={logoUrl} alt="Logo" />
+      <h1>
+        <Trans>Your configuration</Trans>
+      </h1>
+      <div className="summary">
+        {$root.$summary.map((item, i) => (
+          <p key={i}>
+            <strong>
+              <HtmlHelpers.Localized>{item.title}</HtmlHelpers.Localized>
+            </strong>{' '}
+            — {item.price}
+          </p>
+        ))}
+      </div>
+      <p>
+        <ResourceHelpers.Link resource="readRevisionLink">
+          <Trans>Open snapshot</Trans>
+        </ResourceHelpers.Link>
+      </p>
+    </body>
+  </html>
+)
+
+export const PdfHeader = () => (
+  <div style={{ fontSize: 9, padding: '4px 10px', borderBottom: '1px solid #ccc' }}>
+    <Trans>Configuration summary</Trans>
+  </div>
+)
+
+export const PdfFooter = () => (
+  <Trans>
+    Page <PdfHelpers.PageNumber /> of <PdfHelpers.TotalPages />
+  </Trans>
+)
+```
+
+#### Builder chain
+
+Required steps shown uncommented; optional steps as commented lines with their defaults:
+
+```tsx
+ctx.pdfTaskBuilder
+  .withResourceName(resources.simplePdf)
+  // .withLocale('de')                                           // override request locale
+  // .withFormat('A4')                                                       // default 'A4'. Or Letter/Legal/Tabloid/A0–A5, or '{w}x{h}{in|cm|mm}'
+  // .withMargin({ top: '10mm', right: '10mm', bottom: '10mm', left: '10mm' }) // values carry units (`px`/`cm`/`mm`/`in`/`pt`); default '10px' all sides
+  // .withIncludedResources({ other: [...] })                                 // required when templates reference resources
+  // .withReactHeader(<PdfHeader />, { height: '30mm', startAt: 1 })          // omit for no header; `withHtmlHeader` for raw HTML
+  .withReactBody(<PdfBody />) // required; `withHtmlBody` for raw HTML
+  // .withReactFooter(<PdfFooter />, { height: '20mm', startAt: 1 })          // omit for no footer; `withHtmlFooter` for raw HTML
+  // .withWatermarkText('DRAFT', { fontSize: 64, opacity: 30 })               // at most one watermark; or withWatermarkImage / withWatermarkResourceImage
+  .build()
+```
+
+#### Resource helpers
+
+Helpers emit `configuration-resource://<name>` placeholders that the server replaces at render time. The referenced resource must be declared via `withIncludedResources()` — otherwise the render throws.
+
+| Helper                                                            | Use for                                                                      | Resolved to                                                                  |
+| ----------------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `<ResourceHelpers.Link resource="X">`                             | hyperlinks to a resource                                                     | signed URL                                                                   |
+| `<ResourceHelpers.Image resource="X">`                            | embedded images                                                              | signed URL (`embeddingType: 'Link'`) or inlined base64 data URI (`Embedded`) |
+| `<ResourceHelpers.ClientSideImage entityId="…" instanceName="…">` | configurator-rendered images — see [Client-side images](#client-side-images) | resolved client-rendered image                                               |
+
+#### Watermarks
+
+Stamp a single watermark across every page.
+
+- `withWatermarkText(text, options?)` — `text` is a `Localizable` value resolved against the active locale and domain fallback chain.
+- `withWatermarkImage(url, options?)` — `url` is a public URL or a base64 data URI.
+- `withWatermarkResourceImage(resourceName, options?)` — sources the image from a finalize resource, resolved to a signed URL at render time. The resource is auto-declared as a `Link` image — no separate `withIncludedResources()` entry needed.
+
+```tsx
+.withWatermarkText('DRAFT', { fontSize: 64, color: '#cccccc', opacity: 30, rotate: -45 })
+// .withWatermarkImage('https://example.com/stamp.png', { offsetX: 'right', offsetY: 'bottom' })
+// .withWatermarkResourceImage('myStamp', { rotate: 0 })
+```
+
+| Option                | Watermark    | Notes                                                                             |
+| --------------------- | ------------ | --------------------------------------------------------------------------------- |
+| `offsetX` / `offsetY` | text + image | `left`/`center`/`right` & `top`/`middle`/`bottom`, or a number with a unit suffix |
+| `rotate`              | text + image | degrees                                                                           |
+| `fontSize`            | text         | pixels                                                                            |
+| `fontFamily`          | text         | e.g. `Helvetica`                                                                  |
+| `color`               | text         | hex, with or without leading `#`                                                  |
+| `opacity`             | text         | percentage, 0–100                                                                 |
+| `bold` / `italic`     | text         | boolean                                                                           |
+
+Image watermarks support only positioning and rotation — no opacity or styling is applied.
+
+#### PdfShift variables
+
+`PdfHelpers.PageNumber` / `TotalPages` / `Date` / `Title` / `Url` emit literal `{{page}}` / `{{total}}` / `{{date}}` / `{{title}}` / `{{url}}` strings, resolved by PdfShift at render time. Valid **only inside `withReactHeader` / `withReactFooter`** — using them in `withReactBody` throws.
+
+PdfShift's header/footer rendering does not support custom fonts — keep them simple (system fonts only).
+
+### SendStaticEmail Task
+
+Sends an email via Amazon SES. The body is defined as a React tree which the builder renders twice — once for the email's HTML body and once (piped through `html-to-text`) for the plaintext body. `<EmailHelpers.HtmlOnly>` / `<TextOnly>` toggle content per variant. Attachments may reference any previously generated finalize resource (PDF, CSV, image), be supplied inline as base64, or be a configurator-rendered image.
+
+The 'Static' in the task name refers to the fact that the email is generated statically, meaning that the email is generated in the webhook handler and there is no Handlebars template resolution on the server,
+except for resource reference interpolation.
+
+#### Quick example
+
+```tsx
+// src/webhooks/handlers/configurator-finalize-handler/tasks/email-task.tsx
+import { msg } from '@lingui/macro'
+
+import { EmailTemplate } from './email-template.js'
+
+export const simpleEmailTask = phx.webhooks.taskFactory.createSendEmailTask((resources, data, ctx) => {
+  return ctx.emailTaskBuilder
+    .withSender({ from: 'configurator@salsita.app' })
+    .withRecipients({ to: data.finalizeData.emailAddress })
+    .withSubject(msg`Your configuration`)
+    .withBodyResources({
+      other: [
+        { name: resources.ownerLink, type: 'ConfigurationLink' },
+        { name: resources.readRevisionLink, type: 'ConfigurationLink' },
+      ],
+    })
+    .withReactBody(<EmailTemplate />)
+    .withAttachments({
+      other: [{ type: 'resource', filename: msg`summary.pdf`, resource: resources.simplePdf }],
+    })
+    .build()
+})
+```
+
+```tsx
+// src/webhooks/handlers/configurator-finalize-handler/tasks/email-template.tsx
+import { Trans } from '@lingui/macro'
+
+import { EmailHelpers, ResourceHelpers } from '@salsita-ai/sdk/webhook'
+
+export const EmailTemplate = () => (
+  <div>
+    <h2>
+      <Trans>Your configuration!</Trans>
+    </h2>
+    <p>
+      <Trans>Open your configuration:</Trans>
+    </p>
+    <ul>
+      <li>
+        <Trans>Owner link:</Trans>{' '}
+        <ResourceHelpers.Link resource="ownerLink">
+          <Trans>edit</Trans>
+        </ResourceHelpers.Link>
+      </li>
+      <li>
+        <Trans>View-only:</Trans>{' '}
+        <ResourceHelpers.Link resource="readRevisionLink">
+          <Trans>open</Trans>
+        </ResourceHelpers.Link>
+      </li>
+    </ul>
+    <EmailHelpers.TextOnly>
+      <p>
+        <Trans>Open in an HTML-capable mail client for the full layout.</Trans>
+      </p>
+    </EmailHelpers.TextOnly>
+  </div>
+)
+```
+
+#### Builder chain
+
+Required steps shown uncommented; optional steps as commented lines:
+
+```tsx
+ctx.emailTaskBuilder
+  .withSender({ from: 'configurator@salsita.app' })
+  .withRecipients({ to: data.finalizeData.emailAddress })
+  // .withLocale('de')                            // override request locale
+  .withSubject(msg`Your configuration`)
+  // .withBodyResources({ other: [...] })         // required when the body references resources
+  .withReactBody(<EmailTemplate />) // required; `withHtmlBody` for raw HTML
+  // .withPlainTextBody('...')                    // hand-written text body; otherwise auto-converted via html-to-text
+  // .withAttachments({ other: [...] })
+  .build()
+```
+
+`withReactBody` renders the tree twice — once for the HTML body and once piped through `html-to-text` for the plaintext body. Wrap content in `<EmailHelpers.HtmlOnly>` or `<EmailHelpers.TextOnly>` when it should appear in only one variant.
+
+#### Attachments
+
+```ts
+.withAttachments({
+  other: [
+    { type: 'resource', filename: msg`summary.pdf`, resource: resources.simplePdf },
+    { type: 'base64', filename: 'data.txt', data: 'aGVsbG8=' },
+  ],
+  // clientSideImages: [{ entityId, instanceName: 'preview', filename: msg`preview.png` }],
+})
+```
+
+Filenames accept any `Localizable` value; the builder resolves them against the active locale and domain fallback chain.
+
+#### Sender, recipients, reply-to
+
+`withSender` accepts an optional `replyTo` — useful when emails go out from a generic / no-reply sender but replies should land at a tenant / support address. `withRecipients` accepts comma-separated lists in `to`, `cc`, `bcc`.
+
+#### Debugging emails locally
+
+To avoid sending real emails through SES during local development, set the `EMAIL_DUMP_DIR` env variable on the finalize worker to an absolute path. Each outgoing email is then written into a timestamped subfolder (`body.html`, `body.txt`, `meta.json`, attachments, plus an `index.html` preview that opens automatically in the default browser). SES is not initialised while this mode is active.
+
+### SendHttpRequest Task
+
+Sends a HTTP request to the provided URL.
+
+TODO: Provide a simple example
+
+Following example shows a simple task that sends a HTTP request to the provided URL.
+
+```ts
+/**
+ * The SendHttpRequest is used to send an HTTP request to a given URL with the given method, headers and body.
+ */
+export interface SendHttpRequestTask {
+  type: typeof TaskType.SendHttpRequest
+  /**
+   * The URL to send the request to
+   */
+  url: string
+  /**
+   * The HTTP method to use, defaults to GET
+   */
+  method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'CONNECT' | 'OPTIONS' | 'TRACE' | 'PATCH' | undefined
+  /**
+   * The headers to send with the request
+   */
+  headers?: Record<string, string> | undefined
+  /**
+   * The body of the request, (stringified JSON, template or raw text)
+   */
+  body?: string | undefined | Template
+}
+```
+
+### 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.
+
+### EditGoogleSpreadsheet Task
+
+Writes data into a specified Google Sheet as part of the configuration finalization process.
+To enable this functionality, it is necessary for either the client or Salsita to create a target
+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.
+
+```ts
+export interface EditGoogleSpreadsheetTask {
+  type: typeof TaskType.EditGoogleSpreadsheet
+
+  /**
+   * Service account credentials
+   */
+  credentials: Record<string, string>
+
+  /**
+   * The ID of the spreadsheet
+   */
+  spreadsheetId: string
+
+  /**
+   * Any edits to be made to the spreadsheet
+   */
+  edits: GoogleSpreadsheetEdit[]
+}
+```
+
+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.
+
+```ts
+export interface GoogleSpreadsheetEdit {
+  /**
+   * Ranges of cells to edit
+   */
+  ranges: Record<string, Array<Array<string | number | boolean>>>
+
+  /**
+   * Edit mode
+   */
+  mode: GoogleSpreadsheetEditMode
+}
+```
+
+The operations are stored in the `ranges` property. The keys represent references to cell ranges in [A1 notation](https://developers.google.com/sheets/api/guides/concepts). This makes it possible to specify single cells, rectangular areas of cells as well as the sheet that should be edited.
+
+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.
+
+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]
+        ],
+      },
+      mode: 'append',
+    },
+    {
+      ranges: {
+        'Summary!B5': [[new Date().toLocaleString('en-GB')]],
+      },
+      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.
+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.
+
+```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) => {
+    return {
+      // data that will be passed to the callback handler
+      replayData: {
+        emailAddress: state.finalizeData.emailAddress,
+      },
+      // generated resources that should be forwarded to the callback handler
+      resources: {
+        [resources.ownerLink]: {
+          embeddingType: 'Link',
+        },
+        [resources.simplePdf]: {
+          embeddingType: 'Link',
+        },
+        [resources.simpleImage]: {
+          embeddingType: 'Link',
+        },
+        [resources.clientImage]: {
+          embeddingType: 'Link',
+        },
+        [resources.simpleCsv]: {
+          embeddingType: 'Link',
+        },
+      },
+    }
+  })
+  .withCallbackHandler(async data => {
+    // Access resolved resource links and replayData
+    return {
+      emailAddress: data.replayData.emailAddress,
+      pdfLink: data.resources.simplePdf!.link,
+      imageLink: data.resources.simpleImage!.link,
+      clientImageLink: data.resources.clientImage!.link,
+      csvLink: data.resources.simpleCsv!.link,
+    }
+  })
+  .build()
+```
+
+The `FinalizeResult` returned from the callback handler is then passed back to the client, which can retrieve it using `await apiClient.waitForFinalizationToComplete` method.
+
+## 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
+`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.
+
+Compatibility is preserved during upgrades. An older SDK still returns the inline `PublishRevisionChunks` task, which the current server accepts. When a current SDK runs against an older server, no staging URL is present and the SDK falls back to that inline task. Inline responses remain subject to the webhook platform's response-size limit. For the complete chunked publishing flow, see **[Publishing](?path=/docs/phoenix-publishing--docs#publish-flow)**.
+
+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.
+
+You can define the Admin Finalization handler in the following way.
+
+```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()
+```
+
+Before the admin finalization handler is called, the `AdminConfiguration` data are first validated via the admin domain and its violations.
+
+## 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`:
+
+```yaml
+useAuthHook: true
+```
+
+Auth hook can define different types of handlers.
+
+- For Clerk:
+  - CodeFlow Handler
+  - RefreshFlow Handler
+- Custom handlers:
+  - CodeFlow Handler
+  - RefreshFlow Handler
+- AnonymousFlow Handler
+
+```ts
+// src/webhooks/handlers/auth-handler.ts
+export const authHandler = phx.webhooks.authHandlerBuilder
+  // To enable default authentication method with Clerk:
+  .withClerkCodeHandler()
+  .withClerkRefreshHandler()
+
+  // To implement custom auth handlers.
+  // For example to integrate with customer's auth.
+  .withCodeHandler(async payload => {
+    // ... CodeFlow implementation
+  })
+  .withRefreshHandler(async payload => {
+    // .. RefreshFlow implementation
+  })
+
+  // Add to allow anonymous access.
+  .withAnonymousHandler(async () => {
+    return { success: false }
+  })
+
+  // Assign chunk scopes for chunked published data access control.
+  // The system chunk scope ("public") is auto-injected — no need to include it.
+  // See Publishing page for details.
+  .withPublishedChunkScopes(({ role }) => {
+    if (role === 'admin') return ['dealer', 'admin']
+    return []
+  })
+  .build()
+```
+
+For full details on `withPublishedChunkScopes()`, scope resolver patterns, and chunked publishing, see **[Publishing - Access Control](?path=/docs/phoenix-publishing--docs#access-control)**.
+
+### Clerk handlers
+
+For the optional inline Configurator and Admin UI that uses `withClerkSessionHandler()`, see [Clerk Sign-In](?path=/docs/phoenix-clerk-sign-in--docs).
+
+These handlers enable default authentication method with [Clerk](http://clerk.com/) as an authentication provider. Clerk is an external authentication and user management solution,
+which we integrate in two ways:
+
+1. In the configurator and admin interfaces we use Clerk as a standard OAuth provider.
+2. In Studio we use Clerk's React components and API to integrate with their proprietary authentication method.
+
+Let's focus on the first option here, because that's the one we can configure in a webhook. First you need to get all required ENV variables. All of them can be found in [Clerk's Dashboard](https://dashboard.clerk.com/) of your Clerk account.
+
+#### Clerk applications
+
+In Clerk each customer has its own application. Each application has its own set of organizations (groups), users and its own settings. To create one, navigate to [Clerk Applications](https://dashboard.clerk.com/apps)
+and click on `+ Create application`. Give your new appliacation a name and select preferred sign in options. Adding Google will make signups easier and it works out of the box without a need to set up anything in Google Console.
+
+Once the application is created, copy its publishable and secret keys from `[YOUR APP] -> Configure -> API keys`. In Studio, open **Customers**, select the customer, open **Clerk Settings**, and save both keys there. Clerk credentials are managed per customer in Studio, not in the configurator frontend environment.
+
+We get the rest of the Clerk ENVs after creating a new OAuth application in `[YOUR APP] -> Configure -> OAuth applications`. Use any name and set `email openid profile` scopes. How to configure the rest:
+
+- enable `Public` option
+- disable `Consent screen` if you want slighlty easier log in
+- add callback URLs:
+- `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:
+
+```
+# Application credentials -> Client ID
+# Where to put it: webhook
+OAUTH_PROVIDER_CLIENT_ID=xxx
+
+# Application credentials -> Client Secret
+# Where to put it: webhook
+OAUTH_PROVIDER_CLIENT_SECRET=xxx
+
+# 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.
+
+#### Clerk organization
+
+Add a new organization to you new application in Clerk Dashboard - pick any name, leave default settings. Each customer should have exactly one Organization. Organization's metadata are used as a settings storage for your application.
+If you need to make tags available to your application in Studio, configure them in organization's private metadata:
+
+```
+{
+  "userTags": [
+    {
+      "id": "dealer",
+      "label": "Dealer"
+    }
+  ]
+}
+```
+
+#### Phoenix Session Data
+
+Configure your Session Data. With `useClerk` enabled, the schema must declare the complete payload the Clerk handlers return — application-spec parsing rejects the spec with a `CLERK_SESSION_DATA_INCOMPATIBLE` diagnostic otherwise:
+
+```yaml
+sessionData:
+  type: object
+  properties:
+    id:
+      type: string
+    accessToken:
+      type: string
+    tags:
+      type: array
+      items:
+        type: string
+    emailAddress:
+      type: string
+    fullName:
+      type: [string, 'null']
+  required: []
+  additionalProperties: false
+```
+
+Session data properties must remain optional because admin and preset sessions can carry an empty custom payload. Project-specific properties can be added alongside the built-in ones. See **[Sessions and Access - Clerk Integration](?path=/docs/phoenix-sessions-and-access--docs#clerk-integration)** for the full contract.
+
+### Custom auth handlers
+
+#### CodeFlow Handler
+
+CodeFlow solves the problem of safely passing credentials to the client from 3rd party services. It is a two-step process where the 3rd party sends credentials to /callback endpoint
+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.
+
+```ts
+export const authHandler = phx.webhooks.authHandlerBuilder.withCodeHandler(async payload => {
+  // 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...
+
+  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
+    success: true,
+    data: {
+      // custom session data that will be stored in the session - defined via the SessionData type
+    },
+    // role of the user, can be '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,
+  }
+})
+```
+
+`userId` is optional. It identifies the user across browsers and devices, for example to show them the same assistant thread. The server prefixes it as `custom-<userId>` in the session token's `sub`; the builder's Clerk handlers return the Clerk user id, which becomes `clerk-<id>`. A handler that returns no `userId` leaves the session to the browser's anonymous id (`anonymous-<uuid>`). See **[Sessions and Access - Session User](?path=/docs/phoenix-sessions-and-access--docs#session-user)**.
+
+#### 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.
+
+```ts
+export const authHandler = phx.webhooks.authHandlerBuilder.withRefreshHandler(async payload => {
+  // refresh token passed from code handler / client
+  const { refreshToken } = payload
+
+  // Use the refresh token to refresh the session data, fetch user data, etc...
+
+  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
+    success: true,
+    data: {
+      // custom session data that will be stored in the session - defined via the SessionData type
+    },
+    // role of the user, can be '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,
+    // refresh token that will be passed to the refresh flow when the session expires
+    refreshToken,
+    // expiration time of the session in seconds
+    expirationTime,
+  }
+})
+```
+
+### AnonymousFlow Handler
+
+AnonymousFlow is triggered when the session is being authenticated without any credentials or refreshToken.
+
+```ts
+export const authHandler = phx.webhooks.authHandlerBuilder
+  // No payload is passed to the anonymous handler
+  .withAnonymousHandler(async () => {
+    // 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
+      success: true,
+      data: {
+        // custom session data that will be stored in the session - defined via the SessionData type
+      },
+      // role of the user, can be '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,
+    }
+  })
+```
+
+## Advanced Features
+
+The following features provide advanced functionality for complex webhook scenarios. These are optional features that extend the basic webhook capabilities.
+
+## Prefetch Tasks
+
+Prefetch tasks allow you to run data preparation and setup tasks before the main finalization workflow begins. They are executed first in the finalization pipeline and their results are available to all subsequent tasks.
+
+Prefetch handlers are useful for:
+
+- Fetching additional data from external APIs or databases
+- Computing derived values that will be used by multiple tasks
+- Preparing data that will be used by multiple tasks
+
+### Defining a Prefetch Handler
+
+Use `phx.webhooks.prefetchBuilder` to create a prefetch handler:
+
+```ts
+// src/webhooks/handlers/configurator-finalize-handler/tasks/prefetch-handler.ts
+export const prefetchHandler = phx.webhooks.prefetchBuilder
+  .withPrefetchHandler(async (data, ctx) => {
+    ctx.logger.info('Starting prefetch phase')
+
+    // Fetch additional data from external API
+    const productCatalog = await fetchProductCatalog(data.deploymentId)
+    const pricingRules = await fetchPricingRules(data.sessionPayload.region)
+
+    // Compute derived values that multiple tasks will use
+    const totalPrice = calculateTotalPrice(data.state.entities, pricingRules)
+    const estimatedDeliveryDate = calculateDeliveryDate(data.finalizeData.shippingAddress)
+
+    return {
+      prefetchedAt: new Date().toISOString(),
+      productCatalog,
+      totalPrice,
+      estimatedDeliveryDate,
+    }
+  })
+  .build()
+```
+
+### Using Prefetch in Finalization Handler
+
+Add the prefetch handler to your finalization handler using `withPrefetch()`:
+
+```ts
+// src/webhooks/handlers/configurator-finalize-handler/configurator-finalize-handler.ts
+export const configuratorFinalizeHandler = phx.webhooks.finalizeHandlerBuilder
+  .withPrefetch(prefetchHandler) // Add prefetch handler
+  .withTask(pdfGenerationTask)
+  .withTask(emailTask)
+  .withCallback(callbackTask)
+  .build()
+```
+
+### Accessing Prefetched Data
+
+The data returned by your prefetch handler is available to all subsequent tasks as `prefetchedData`:
+
+```ts
+// 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
+  }
+})
+```
+
+### Prefetch Task Interface
+
+The prefetch handler receives `PrefetchTaskData` which includes all configuration and session information:
+
+```ts
+export interface PrefetchTaskData<
+  FINALIZE_DATA extends Record<string, unknown>,
+  ENTITIES extends DomainEntity<string>,
+  PUBLISHED_DATA extends Record<string, unknown>,
+  SESSION_DATA extends Record<string, unknown>,
+  FRONTEND_DATA extends Record<string, unknown>,
+> {
+  configurationId: ConfigurationId
+  revisionId: RevisionId
+  deploymentId: DeploymentId
+  frontendUrl: FrontendUrl
+  state: DomainState<ENTITIES>
+  finalizeData: FINALIZE_DATA
+  sessionRole: SessionRole
+  sessionPayload: SESSION_DATA
+  publishedData: PUBLISHED_DATA
+  frontendData: FRONTEND_DATA
+  backendData: Record<string, unknown> | undefined
+}
+```
+
+## 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.
+
+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.
+
+### Available Resource Creation Methods
+
+The `phx.webhooks.dynamicResourcesFactory` provides methods for creating different types of resources:
+
+```ts
+// src/webhooks/handlers/dynamic-resources.ts
+
+// Server-generated images
+const generatedImageHandler = phx.webhooks.dynamicResourcesFactory.createGeneratedImage((resources, data, ctx) => {
+  return {
+    type: 'GeneratedImage',
+    name: 'dynamicServerImage',
+    s3Key: `generated/${data.configurationId}/render.png`,
+  }
+})
+
+// Dynamic links
+const linkHandler = phx.webhooks.dynamicResourcesFactory.createLink((resources, data, ctx) => {
+  return {
+    type: 'Link',
+    name: 'customShareLink',
+    url: `${data.frontendUrl}/share/${data.configurationId}?utm_source=dynamic`,
+  }
+})
+
+// Dynamic PDFs
+const pdfHandler = phx.webhooks.dynamicResourcesFactory.createPdf((resources, data, ctx) => {
+  return {
+    type: 'Pdf',
+    name: 'dynamicReport',
+    s3Key: `reports/${data.configurationId}/report.pdf`,
+  }
+})
+```
+
+Other available methods include: `createClientGeneratedImage`, `createExistingImage`, `createCsv`, and `createResource`.
+
+### Conditional Resource Creation
+
+Dynamic resources excel at conditional logic based on configuration state:
+
+```ts
+const conditionalImageHandler = phx.webhooks.dynamicResourcesFactory.createGeneratedImage((resources, data, ctx) => {
+  const entities = data.state.entities
+  const hasCustomMaterial = entities.some(entity => entity.type === 'Material' && entity.custom === true)
+
+  // Only create image if custom materials are used
+  if (!hasCustomMaterial) {
+    return null
+  }
+
+  return {
+    type: 'GeneratedImage',
+    name: 'customMaterialPreview',
+    s3Key: `previews/${data.configurationId}/custom-materials.png`,
+  }
+})
+```
+
+### Multiple Resource Creation
+
+Handlers can return arrays to create multiple resources:
+
+```ts
+const multipleImagesHandler = phx.webhooks.dynamicResourcesFactory.createGeneratedImage((resources, data, ctx) => {
+  const colorOptions = data.finalizeData.requestedColors || []
+
+  return colorOptions.map((color, index) => ({
+    type: 'GeneratedImage',
+    name: `colorPreview${index}`,
+    s3Key: `colors/${data.configurationId}/${color}.png`,
+  }))
+})
+```
+
+### Using Dynamic Resources in Tasks
+
+Dynamic resources are automatically available to finalization tasks:
+
+```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: [],
+  }
+})
+```
+
+## 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.
+
+### Defining a Backend Data Handler
+
+Backend data handlers are defined inline in the webhook builder:
+
+```ts
+// src/webhooks/index.ts
+export default phx.webhooks.webhookBuilder
+  .withAuthHook(authHandler)
+  .withConfiguratorFinalize(configuratorFinalizeHandler)
+  .withFetchBackendData(async ({ frontendData, sessionPayload, deploymentId }, { 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)
+
+    return {
+      backendData: {
+        userProfile,
+        pricingData,
+        fetchedAt: new Date().toISOString(),
+      },
+    }
+  })
+  .build()
+```
+
+### Backend Data in application.yaml
+
+Define the schema for backend data in `spec/application.yaml`:
+
+```yaml
+# spec/application.yaml
+backendData:
+  type: object
+  properties:
+    exchangeRateAtStartTime:
+      type: number
+    userProfile:
+      type: object
+  required:
+    - exchangeRateAtStartTime
+  additionalProperties: false
+```
+
+### Accessing Backend Data
+
+Backend data is automatically fetched and made available throughout your application:
+
+**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:
+
+```ts
+// 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)
+
+    return {
+      discountRate,
+      finalPrice,
+      recommendedProducts,
+      userTier: userProfile?.tier,
+    }
+  })
+  .build()
+
+// Tasks also receive backend data
+export const pricingTask = phx.webhooks.taskFactory.createGeneratePdfTask((resources, data, ctx) => {
+  const { pricingData } = data.backendData || {}
+
+  return {
+    type: 'GeneratePdf',
+    name: resources.pricingReport,
+    html: {
+      template: '<h1>Price: ${"{{"}price{{"}}"}}</h1>',
+      data: {
+        price: pricingData?.totalPrice || 'N/A',
+      },
+      includeResources: [],
+    },
+    // ... rest of PDF configuration
+  }
+})
+```
+
+### Backend Data Interface
+
+The backend data handler receives comprehensive request information:
+
+```ts
+export interface FetchBackendDataPayload<
+  SESSION_DATA extends Record<string, unknown>,
+  FRONTEND_DATA extends Record<string, unknown>,
+> {
+  deploymentId: DeploymentId
+  frontendUrl: FrontendUrl
+  frontendData: FRONTEND_DATA
+  sessionRole: SessionRole
+  sessionPayload: SESSION_DATA
+  publishedAdminRevisionPath: string | undefined
+}
+```
+
+### Use Cases
+
+Backend data handlers are ideal when you need to:
+
+- Fetch data using API keys that cannot be exposed to the client
+- Access private databases or internal services
+- Perform server-side authentication with external systems
+- Retrieve data that should be available both in the domain and webhooks
+
+The fetched data becomes available throughout your application while keeping sensitive credentials secure on the server.
+
+## Legacy: Handlebars templates
+
+The Handlebars `Template` form is retained side-by-side with the React variant for projects that already use it. New configurators should use React templates instead (see [GenerateStaticPdf](#generatestaticpdf-task) and [SendStaticEmail](#sendstaticemail-task)).
+
+The legacy `GeneratePdfTask` and `SendEmailTask` return a plain object with `type: 'GeneratePdf'` / `'SendEmail'` and `html: Template` instead of calling the builder. `SendHttpRequest`'s `body` field also accepts the same `Template` shape.
+
+```ts
+const template: Template = {
+  template: `
+    <h1>{{someData}}</h1>
+    <a href={{resource-ownerLink}}>edit</a>
+  `,
+  data: { someData: 'Hello World!' },
+  includeResources: [{ name: resources.ownerLink, type: 'ConfigurationLink' }],
+}
+```
+
+Templates are compiled with Handlebars; resources referenced via `{{resource-<name>}}` must be listed in `includeResources`.
+
+## What We Learned
+
+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
+- **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
+
+**Advanced Features:**
+
+- **Prefetch tasks** enable data preparation and computation before main finalization processing
+- **Dynamic resources factory** creates resources at runtime based on configuration state and user data
+- **Backend data handlers** securely fetch data with API keys while making it available throughout the application
+
+Webhooks transform Phoenix from a static configurator into a dynamic, server-integrated platform.
+
+## Next Steps
+
+Now that you understand Phoenix's webhook system, explore these related topics:
+
+- **[Finalization](?path=/docs/phoenix-finalization--docs)** - Deep dive into finalization workflows and client-side integration
+- **[Data Sources](?path=/docs/phoenix-data-sources--docs)** - Learn about session, published, and backend data used in webhooks
+- **[Expression Context](?path=/docs/phoenix-expression-context--docs)** - Access webhook data in domain expressions and components
+- **[Domain Model](?path=/docs/phoenix-domain-model--docs)** - Understand the foundation that webhooks extend with server capabilities
+- **[Best Practices](?path=/docs/phoenix-best-practices--docs)** - Follow proven patterns for webhook implementation and deployment
+
+For hands-on practice, explore webhook examples in the **[demo projects](?path=/docs/phoenix-quickstart--docs)** and finalization workflows.