feat: webhook trigger

CHANGELOG.md

@@ -1,3 +1,21 @@
+## [0.5.0] - Unreleased
+
+### Changed
+- **DataGrout Trigger** receives events over a webhook instead of a WebSocket.
+  Activating the workflow registers a webhook subscription on your DataGrout
+  server for the selected events, pointed at the URL n8n gives the node;
+  DataGrout POSTs each event there, and deactivating the workflow removes the
+  subscription. Every delivery must carry the secret issued at registration, or
+  it is answered 401 and the workflow does not start. The events and the fields
+  they carry are unchanged. Needs a DataGrout server whose REST API has
+  `/webhooks`.
+
+### Removed
+- The trigger's **Reconnect Automatically** and **Topic** options, its Node 22
+  requirement, and its switching-on of the server's WebSocket transport.
+- **Test step** on the trigger no longer emits a synthetic example event. Use
+  **Listen for test event** and cause a real one.
+
 ## [0.4.0] - 2026-10-14
 
 **Breaking.** The node is now organised around DataGrout operations instead of

README.md

@@ -29,8 +29,8 @@ No runtime dependencies.
   in the next, and in other workflows pointed at the same memory.
 - **Compute that stays next to the data.** A large result never has to travel
   through your workflow to be grouped or aggregated.
-- **Events pushed to you.** One WebSocket, no polling, no webhook URL to paste
-  into a dashboard.
+- **Events pushed to you.** The trigger registers its own webhook with DataGrout
+  when you activate the workflow: no polling, nothing to paste into a dashboard.
 
 ## Operations
 
@@ -66,8 +66,10 @@ and from what follows logically from them, with no model call.
 
 ## DataGrout Trigger
 
-DataGrout publishes every server event to one topic, so the trigger subscribes
-once and you pick the events you want:
+Activating the workflow registers a webhook with your DataGrout server, pointed
+at the URL n8n gives the trigger. DataGrout then POSTs each event straight to
+n8n, and deactivating the workflow removes the registration. You pick the
+events you want:
 
 | Event | Carries |
 | --- | --- |
@@ -90,13 +92,17 @@ that result server-side without re-fetching or recomputing it.
 `run_id` is the integer DataGrout's own `runs.get` accepts, so a following node
 can fetch the full run without translating anything.
 
-Connection lifecycle frames are filtered out, so a reconnect does not start your
-workflow. The connection is held open with a keepalive, and a genuinely dropped
-one reopens on a backing-off delay.
+Each registration comes with a secret that DataGrout presents on every delivery.
+A request without it is answered 401 and never starts your workflow, and an
+event you did not select is acknowledged and dropped.
 
-Press **Test step** in the editor to emit an example carrying the real fields of
-whichever event you selected, so you can wire downstream nodes before a real
-event happens.
+DataGrout must be able to reach n8n over HTTPS at a public address. It refuses
+plain HTTP and any `localhost` or private-network URL, so a self-hosted instance
+needs a public `WEBHOOK_URL`.
+
+Press **Listen for test event** in the editor, then make something happen in
+DataGrout — a run finishing, a task failing — and the event lands in the editor
+so you can wire downstream nodes against its real fields.
 
 ## Examples
 
@@ -135,10 +141,6 @@ token itself names the server it was granted.
 Testing a credential only reads — it fetches the server's name, changes nothing
 and costs nothing.
 
-The trigger listens over DataGrout's WebSocket transport, which a new server has
-switched off. It switches it on when the trigger starts, and writes that to the
-n8n log, so a change to your server's settings is never silent.
-
 ## Using it with an AI Agent
 
 The free-text fields default to `$fromAI(...)`, so an agent can fill them in with
@@ -158,19 +160,11 @@ certificate and reference.
 On the trigger:
 
 - **Include Event Name** — add the event name to each item as `event`.
-- **Reconnect Automatically** — reopen a dropped connection.
-- **Topic** — change only to follow a single orchestration run, which publishes
-  to a topic of its own.
 
 ## Compatibility
 
 Tested against n8n 2.36 on Node 24.
 
-The trigger uses Node's built-in WebSocket, which keeps this package free of
-runtime dependencies and needs Node 22 or newer. n8n 2.x requires Node 24, so
-that is already satisfied; on a much older n8n running Node 20 the trigger
-reports what it needs instead of failing obscurely.
-
 ## Development
 
 ```bash

examples/README.md

@@ -24,14 +24,15 @@ so the next node transforms that result server-side without re-fetching or
 re-computing anything. This is why `cache_ref` is on the wire.
 
 **Import**, then attach a DataGrout credential to both nodes and activate the
-workflow. Use **Test step** on the trigger to emit a shaped example if you want
-to wire the downstream node before a real task finishes.
+workflow, which registers the webhook with DataGrout. To wire the downstream
+node first, press **Listen for test event** on the trigger and let a real task
+finish.
 
 ## `datagrout-trigger-failures.json` — route failures
 
-DataGrout publishes every server event to one topic, so a workflow subscribes
-once and branches on `event`. This one listens for `task.failed` and
-`tool_call.failed` and splits them.
+One trigger can register for several events, and each item says which one
+arrived in `event`, so a workflow branches on it. This one listens for
+`task.failed` and `tool_call.failed` and splits them.
 
 `task.failed` is the one nothing else reports: whoever started the task stopped
 waiting long before it failed. Replace the two No-Op nodes with whatever you