Event Flow Manifest authoring guide

An Event Flow Manifest is the flows[] portion of a connector config. This guide teaches you to author working inbound and outbound flows without reading the runtime source. The per-field schema (every field, every validator, the full action DSL) lives in ../config-v3/ and is not repeated here.

Mental model

A producer puts a message on a queue. The message envelope carries two fields: source_name and event_type. flow_worker loads the connector’s published config from DynamoDB, matches every flow whose source equals source_name and whose event_type equals or wildcard-matches event_type (cliente.* matches cliente.creato; exact match wins when both match the same event - see ../config-v3/flows.md#wildcard-event_type), and runs each matching flow’s steps in order.

Steps read and write a shared per-execution context:

• $.payload.* - the inbound event body as received.
• $.canonical.* - a shared dict a transform step writes into; later steps read from it.
• $<step-id> / $.<step-id>.* - the output of an earlier named step in the same flow.
• when - an optional condition that gates whether a step runs at all (see ../config-v3/step-actions.md).

There is no direction field on a flow: nothing on a flow declares its direction. Two derived notions of direction coexist, and they answer different questions.

• Routing and counting follow the QUEUE the event travelled on, which follows the EventSource that emitted it: source_worker puts HubSpot journal events on outbound-sync.fifo, the Event API puts webhooks on inbound-sync.fifo. This is the direction recorded on each processed event, and the one the Analytics panel filters by. See event-sources.md.
• The badge on a flow (flow list in the dashboard, plus the connector-level badge in the header) is derived from the flow’s STEPS: a flow that writes to HubSpot is inbound, any other flow is outbound, and the connector is bidirectional when it has both. Reading HubSpot (find, find_associated) does not make a flow inbound. The rule lives in one place, (internal plugsync tooling - see the source repo), and the draft API serves it (issue #1203).

The two axes can disagree, by design. A journal-driven flow that pushes a document to an external system and then writes the returned id back onto the HubSpot record (Compass’ hubspot_deal_generate_doc, walked through in ../plugins/generate-doc-walkthrough.md) travelled on the outbound queue, so Analytics counts its events as outbound, while its steps do write to HubSpot, so the flow list badges it inbound. Neither is wrong: one describes where the event came from, the other what the flow does.

How events flow

INBOUND  (an external system writes into HubSpot)

  external system --POST--> Event API / webhook         [EventSource: webhook | event_api]
                                  |
                                  v
                          inbound-sync.fifo  (SQS)
                                  |
                                  v
                             flow_worker      (matches source_name + event_type, runs steps)
                                  |
                                  v
                              HubSpot

OUTBOUND  (a HubSpot change flows out to a target system)

  HubSpot journal v4  \
  REST poller          >--- source_worker polls --->  queue (SQS)   [EventSource: hubspot | poller | scheduled]
  scheduled tick      /                                  |
                                                         v
                                                    flow_worker     (matches source_name + event_type, runs steps)
                                                         |
                                                         v
                                                     target API     (post step)

Prerequisites

Before authoring flows:

1. You have a Plugsync org and an authenticated user.
2. You have completed the HubSpot OAuth flow once (so a HubSpot credential exists in your org).
3. You have created a connector via the dashboard or POST /api/connectors.
4. You have created at least one EventSource that the flow’s source will reference (see event-sources.md).

Where to read next

Out of scope

This guide deliberately does not cover:

• Schema reference (every field and validator). See ../config-v3/ and #ENG-56.
• Plugin steps (Lambda + TypeScript). See the Plugin runtime guide.
• Getting-started tutorial. See #ENG-59.
• flow_runtime internals.