Concepts
How webhooks, workflows, hops, tasks, and runs fit together.
Connect is built around a few objects. Understanding how they relate is enough to operate the portal and to integrate without guessing at API layers.
How these concepts fit together
A partner posts a signed webhook event. Connect persists it, then retryably starts a workflow. The workflow is a graph of hops — calls, waits, forks, switches, ends. When a hop listens, a task appears for an operator. Everything for that start shares one correlation id and one run envelope. Approved work may land in Plane; integrators read it back through Experience APIs.
- Webhook
- Inbound HMAC event. Unique per partner and external id. Starts at most one workflow.
- Workflow
- Durable graph from the catalog. Snapshotted when the run starts.
- Hop
- One step: call a Camel route, wait for a person, fork, switch, or end.
- Task
- A waiting listen, shown in Tasks. The operator decides; the partner never logs in.
- Run
- The envelope for one correlation — trigger, hops, status, result.
- Catalog
- Versioned artifacts: APIs, events, jobs, workflows, webhooks.
- Consumer
- Machine client with an API key and grants for published APIs.
Mental model
- webhook events track inbound work from partners
- workflows own the hops those events move through
- tasks are the human waits on those hops
- runs are how you inspect one correlation
- catalog is what you publish; consumers are who may call it
Workflow id vs correlation id
The Temporal workflow id is the correlation id issued on HMAC accept. Do not use partnerId:externalId as a workflow id. Duplicate events return 200 Duplicate and do not start a second run.
Jobs vs workflows
Jobs are Camel-only and have no wait. Workflows are durable orchestration: hops, waits, forks, exclusive branches. The two builders never share a canvas.
API layers
Partners and product consumers call Experience APIs (EAPI). Operators use the portal, which calls System APIs (SAPI). You do not need those names to use Connect. They matter when you open APIs. Details: API layers.
Contact-lead journey
Website form → HMAC webhook (eventType: contact.lead) → contact-lead workflow → fork (Matrix notify and operator Review) → approve creates a Plane issue → GET /api/v1/leads reads Plane.