Event nodes

An event node is the starting point of a topology — the place a message comes in from. Orchesty exposes three flavours, each suited to a different trigger source:

For background see Concepts: Topologies. For the Webhook subscription lifecycle, the SDK contract, and orphan handling, see Patterns: Webhooks.

Common UI surface #

Every event node exposes the same skeleton in the topology canvas:

• A two-state label above the node summarising whether the event is active (Disable / Enable for Start and Cron; Off / Subscribed for Webhook).
• An inline action bar with the most common operations (Disable | Run | Copy URL for Start and Cron; Subscribe / Unsubscribe / Copy URL for Webhook).
• A right-click context menu with the same actions plus power-user variants (e.g. Copy strict version URL for Start).

A node is greyed out on the canvas whenever it cannot fire:

• Start / Cron — when its enabled flag is off in the topology detail.
• Webhook — when no live subscription exists (registered: false).

The visual treatment is unified across all three so an operator can tell at a glance which entry points are actually live.

Start event #

A Start event is the simplest externally-callable entry point. Drop the node into the canvas, connect it to the first action node, save and publish. There is no worker code and no Application — just a named node that resolves to a stable HTTP URL once the topology is published.

Name-based URL — recommended default #

{base}/topologies/{topologyName}/nodes/{nodeName}/run-by-name

• Resolves at request time to whichever topology version is currently enabled for the given name. Republish a new version and integrators keep hitting the same URL.
• Available from the inline Copy URL action and from the Copy URL entry in the right-click menu.
• Returns 404 for an unknown topology name and for a topology that has no enabled version.
• Routed through the API gateway — calls must carry an authorization token.

Strict version URL — power-user only #

{base}/topologies/{topologyId}/nodes/{nodeId}/run

• Pinned to one specific topology version via Mongo ObjectIds. Useful for rollback testing, A/B comparison, or locking a tester to a specific build.
• Reachable only from the right-click menu under Copy strict version URL — the inline label stays clean.
• Same authentication requirements as the name-based variant.

Manual run #

The Run action on the canvas opens a small dialog where you can paste a JSON body and fire the topology in one click. This is the fastest way to debug a topology while you are wiring it up — no curl, no Bearer token, no second tool.

Calling from outside #

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "$BASE/topologies/order-sync/nodes/start/run-by-name" \
  -d '{"orderId": 42}'

$BASE is the API gateway base URL exposed by your instance. Disable a Start event from the canvas (or the topology detail) to stop accepting calls without removing the node.

Cron event #

A Cron event runs the topology on a fixed schedule. There is no callback URL and no Application: the platform's cron-api service is what fires the trigger when the expression matches.

Per-node configuration #

Open the node (double-click or right-click → settings) and set:

• Name — a human-readable identifier scoped to the topology.
• Crontab — standard five-field expression (minute hour day-of-month month day-of-week).
• Parameters — optional JSON object passed as the body of every scheduled run.

The dialog renders a human-readable description of the expression and the next two fire times so you can verify the cadence at a glance.

Crontab examples #

Scheduled Tasks page #

Every Cron node across every topology is also listed on the global Scheduled Tasks page (/scheduled-tasks in the Admin UI). Use it to:

• Enable / disable individual schedules without opening the topology.
• Spot topologies that have a Cron node with Cron is not set (an empty crontab) — the row shows a red warning and never fires until you fix it.
• See the next run time per schedule.

Behaviour notes #

• Per-node disable keeps the schedule entry on the topology but stops it from firing. Re-enable from the canvas, the topology detail, or the Scheduled Tasks page.
• No callback URL — Cron is push by the platform; integrators never call it.
• ApplicationTypeEnum.CRON is not used for plain scheduled topology starts. That enum is reserved for applications whose lifecycle is cron-driven (typically polling syncs that need to refresh state on a tick); a topology with a Cron node needs no application at all.

For the handler patterns inside the topology that runs on a schedule (watermark vs full-snapshot, overlap, time zones, catch-up), see Patterns: Scheduled processes.

Webhook event #

A Webhook event is an entry point whose lifecycle is owned by an Application. The flow is:

1. The user installs an Application that extends AWebhookApplication.
2. The user drops a Webhook node into a topology and picks one of the events the Application advertises (<application>.<event>).
3. The user clicks Subscribe in the topology detail. The platform calls the Application's subscribe DTO upstream and stores the live registration.
4. The third-party service POSTs to the resulting token-protected URL whenever the event fires.

For the SDK contract, the Subscribe / Unsubscribe lifecycle, parameter handling, the cascade on topology enable / disable, and the orphan banner, see Patterns: Webhooks. This section covers only what the canvas exposes.

Picking a subscription in the editor #

The picker is built into the editor. After you drop a Webhook node:

• Double-click the node — opens a search-friendly submenu listing every webhook event from every installed AWebhookApplication. Each entry shows <app>.<event> and the human-readable description the Application advertises.
• Right-click → Pick subscription — same menu, accessed from the context menu instead.

Selecting an event sets the node's action and — importantly — its name to the canonical <application>.<event> form. Webhook nodes are not user-renameable: the editor hides the rename UI for Webhook circles and the schema parser re-derives the canonical name on save, so even hand-crafted schema imports cannot drift away from the convention.

Lifecycle actions on the topology detail #

Once the topology is published, the detail page exposes the full lifecycle on the webhook node:

To change parameters on a live webhook, click Unsubscribe and then Subscribe again — the modal pre-fills the parameter field with the values used last time, so re-confirming is a single click.

Callback URL #

{startingPoint}/topologies/{topology}/nodes/{node}/token/{token}/run

• Token-protected, not Bearer. The token is generated when the webhook is subscribed and is the only authentication the route enforces. Treat the URL as a credential; anyone holding it can fire the event.
• Available only when the webhook is Subscribed — Copy URL refuses to copy a URL without a live token and shows a warning toast instead. There is no ID-based debug variant for webhooks because external providers cannot post to those.
• The same canonical URL is used by the SDK when registering with the upstream provider and by the UI when you click Copy URL.

curl -X POST \
  -H "Content-Type: application/json" \
  "$STARTING_POINT/topologies/order-sync/nodes/pipedrive.order.created/token/$TOKEN/run" \
  -d '{ "id": 42, "status": "created" }'

$STARTING_POINT is the public starting-point URL of your instance.

See also #

• Concepts: Topologies
• Patterns: Webhooks — SDK contract, lifecycle, orphan handling
• Patterns: Scheduled processes — handler patterns for cron-driven topologies
• Operations: Webhook operations — self-hosted migrations and diagnostic CLI
• Reference: Node.js / AWebhookApplication
• Reference: Node.js / WebhookSubscription