> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Event delivery paths — integration guide

> Version: 1.0.0 Last Updated: 2026-03-19 Owner: Platform / FW (cross-cutting) Related: EVENT_CONTRACTS.md, FW_BUSINESS_AUTOMATION_WORKFLOW_RECOMMENDATIONS.md (R…

**Version:** 1.0.0\
**Last Updated:** 2026-03-19\
**Owner:** Platform / FW (cross-cutting)\
**Related:** [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md), [FW\_BUSINESS\_AUTOMATION\_WORKFLOW\_RECOMMENDATIONS.md](../../../specs/fw/FW_BUSINESS_AUTOMATION_WORKFLOW_RECOMMENDATIONS.md) (R-FW-12)

This document explains **which delivery mechanism to use** when integrating features with domain events, automations, and workflows. It does not replace per-spec payloads; use EVENT\_CONTRACTS for event names and schemas.

***

## 1. Table-driven path (FW automation / workflows)

**Flow (high level):** `publishEvent()` (client or server) → `fw_domain_events` → DB trigger `fw_process_domain_event()` → matching automation rules / workflow definitions → `fw_workflow_executions` rows in `queued` (and pgmq enqueue per **FW-46**) → **`workflow-executor-worker`** processes steps.

**Use when:**

* You need **durable, retried** execution with DLQ (FW-47), checkpoints (FW-48), and execution timeouts (FW-49).
* Triggers are registered against **`fw_workflow_events`** / FW-16 event names.

**Do not use for:** Fire-and-forget UI-only updates (use realtime instead).

***

## 2. HTTP `event-consumer` path

**Flow:** `supabase.functions.invoke('event-consumer', { body: { event_type, payload, ... } })` (or equivalent server-side invoke) → handlers registered for that consumer.

**Use when:**

* You need **immediate side effects** (e.g. cross-core notifications, lightweight transitions) where FW’s queued execution model is unnecessary.
* Handlers are **idempotent** where possible; consider that this path may not offer the same **DLQ/checkpoint** guarantees as FW-46 unless you add them explicitly.

**When to add handlers:** When a core needs synchronous-style reactions to an event type that is **not** modeled as an FW automation trigger, or when migrating legacy `pg_notify` consumers.

***

## 3. Realtime path (UI only)

**Mechanisms:** Supabase **Postgres Changes**, **Broadcast**, or app-level subscriptions.

**Use when:**

* **Screens and dashboards** must refresh when data changes.
* You want **low-latency** UX without polling.

**Never use for:** Authoritative server-side routing of business logic, payment, or compliance-critical chains. Realtime delivery is best-effort from the UI perspective; durable work belongs in §1.

***

## 4. External delivery (webhooks / outbound)

**Flow:** Platform event subscriptions (e.g. **PF-35** webhooks) forward selected events to external systems.

**Use when:**

* A vendor, data warehouse, or partner needs **outbound** notification.
* You have **contracts and retries** appropriate for external HTTP (timeouts, signing, secret rotation).

***

## 5. Decision tree

```mermaid theme={null}
flowchart TD
  needDurable[Need_durable_retry_DLQ]
  tablePath[Use_table-driven_FW_path]
  needImmediate[Need_immediate_handler]
  httpPath[Use_event-consumer_or_core_edge_fn]
  uiOnly[UI_refresh_only]
  realtimePath[Use_realtime]
  external[External_partner_system]
  webhookPath[Use_PF-35_webhooks]

  start[Integration_need] --> needDurable
  needDurable -->|yes| tablePath
  needDurable -->|no| needImmediate
  needImmediate -->|yes| httpPath
  needImmediate -->|no| uiOnly
  uiOnly -->|yes| realtimePath
  uiOnly -->|no| external
  external -->|yes| webhookPath
```

| Question                                                                | If yes →                                |
| ----------------------------------------------------------------------- | --------------------------------------- |
| Must the action **survive restarts** and support **DLQ / step replay**? | §1 Table-driven (FW-46+)                |
| Is it **only** to refresh a React view?                                 | §3 Realtime                             |
| Is it **outbound to a third-party URL** with subscription management?   | §4 External / PF-35                     |
| Is it a **one-off server reaction** with no workflow?                   | §2 HTTP consumer (evaluate idempotency) |

***

## 6. FW-49 / FW-47 events in the catalog

Timeout and DLQ **operational** events (e.g. `workflow.execution.timed_out`, DLQ threshold alerts) are documented in **EVENT\_CONTRACTS.md**. They complement the table-driven path: timeouts and permanent failures are detected by scheduled/worker logic and recorded or notified per FW-49 / FW-47.

***

## See also

* [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md)
* [API\_CONTRACTS.md](./API_CONTRACTS.md) — `workflow-executor-worker`, `workflow-timeout-checker`, `extend-execution-deadline`, `evaluate-decision-table`
* [FW-47-dead-letter-queue-INTEGRATION.md](./dead-letter-queue-integration.md)
* [FW-49-execution-timeout-watchdog-INTEGRATION.md](./execution-timeout-watchdog-integration.md)
* [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md)