Chapter 5: Start a topology from an event

Every topology so far started on a schedule (Cron) or a manual run. Many integrations instead need to react the moment something happens in another system. In this chapter you'll import a topology that starts from a Webhook trigger and reacts to an incoming event.

By the end you'll understand how an external event flows into a topology without polling.

Prerequisites #

Reuse the setup from the earlier chapters: the demo worker is running and connected to your platform, and the mock server is running (npm run mock-server). Here the mock server plays the role of the external system that sends the events.

What's new in this chapter #

Webhook trigger. Instead of a Cron node, this topology begins with a Webhook trigger (a circle labelled Webhook). It's the entry point the platform gives a callback URL to; when an event arrives there, the topology runs. No worker node is needed to receive the event; the trigger passes the payload straight to the next node. Background: Patterns: Webhooks.

Webhook application. A webhook flow needs a WEBHOOK-type application that declares which events can be subscribed to and knows how to register and unregister them with the source system. Here Webhook Test declares events like order.created and, on subscribe, registers the platform's callback URL with the mock server. The platform then owns the whole subscribe / deliver / unsubscribe lifecycle for you.

The rest of the topology is just the familiar add-timestamp custom node from Chapter 1, so you can watch each delivered event get enriched.

Import and run #

1. Import demo-webhook.tplg.json from the demo worker's src/topologies/ folder, then Publish and Enable it.
2. Install the Webhook Test application in the Admin UI and Activate it (it needs no credentials).
3. Open the topology and subscribe the order.created event to its Webhook trigger node. On subscribe, the platform builds a callback URL and registers it with the application (which forwards it to the mock server).

Now the mock server POSTs a test event to that callback URL once a minute, so the Webhook trigger fires on its own and add-timestamp enriches each delivered payload. To skip the wait, fire one delivery immediately from the mock server (POST /webhooks/:id/trigger); the exact endpoints are listed in the demo worker's README. Unsubscribing in the UI stops the deliveries.

Where next #

You've now seen how a topology can start on a schedule (Cron) and how it can start from an incoming request. That request entry point comes in two flavours: a plain Event, which simply exposes a URL you can call, and a Webhook, which builds on the Event by also registering and unregistering that URL with the source system automatically (what this chapter used). Together with connectors, a batch, a mapper, and the Limiter, that's the core toolkit.

In Chapter 6 you'll import the demo-forms topology and see how an application's settings forms drive what a node produces, with no code edits.