Skip to Content
ReferenceFlows & event sourcesOverview

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. The per-field schema (every field, every validator, the full action DSL) lives in ../config-v3/ and is not repeated here.

Mental model

Every event enters plugsync as a message whose envelope carries two fields: source_name and event_type. Against the connector’s currently published config, plugsync matches every flow whose source equals source_name and whose event_type equals or wildcard-matches event_type (cliente.* matches cliente.creato; when several flows match the same event only the most specific one runs - an exact match over any wildcard, the longest prefix between wildcards - 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 CHANNEL the event travelled on, which follows the EventSource that emitted it: HubSpot journal events arrive on the outbound channel, events posted to the Event API on the inbound one. 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 draft API serves the same badge the dashboard shows, so the two never disagree.

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 (the hubspot_deal_generate_doc flow walked through in ../plugins/generate-doc-walkthrough.md) arrived on the outbound channel, 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 channel
                                  |
                                  v
                           flow matching        (source_name + event_type, then steps in order)
                                  |
                                  v
                              HubSpot

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

  HubSpot journal v4  \
  REST poller          >---- polled on a tick ---->  outbound channel   [EventSource: hubspot | poller | scheduled]
  scheduled tick      /                                  |
                                                         v
                                                  flow matching     (source_name + event_type, then steps in order)
                                                         |
                                                         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).
PageWhat is there
event-sources.mdCreate the inbound/outbound channels a flow’s source references.
authoring-a-flow.mdTwo end-to-end walkthroughs + how to pick an action.
loop-prevention-and-conflicts.mdThe four echo/conflict guards, whether a write from another tool is seen, and where a suppression shows up.
scheduled-exports.mdA nightly job that reads one day of HubSpot records and writes them to a CSV file: the query and export_file steps.
_examples/Three copy-pasteable configs + their EventSource payloads. The individual files are linked from the pages above.
../config-v3/The field-level schema reference (every field, validator, the 15-action DSL).

Out of scope

This guide deliberately does not cover:

Last updated on
OverviewEvent sources