Guides

Webhooks — Event-Driven Architecture and Lifecycle

How Orchesty handles real-time webhook integrations — from secure endpoint exposure to subscription lifecycle management and cleanup.

In the world of integrations, efficiency is often measured by latency. Scheduled jobs (CRON) are great, but for real-time responsiveness, you need Webhooks. In Orchesty, a Webhook is a specialized type of Starting Node that turns your integration into a reactive listener.

1. Webhooks vs. Standard Start Events #

On the surface, both a Webhook and a Start Event provide an endpoint for external data. However, they differ significantly in how they handle Security and URL structure:

  • Standard Start Event: Usually expects an authorization token in the HTTP header or as a separate credential.
  • Webhook: Since many third-party services have rigid requirements for how they send data, Orchesty Webhooks incorporate the authorization token directly into the URL. This makes them "plug-and-play" with almost any external service that supports a callback URL.

2. The Webhook Application: Managing the Lifecycle #

A unique strength of Orchesty is that it doesn't just provide a URL; it manages the entire lifecycle of the connection. This is handled by a specialized Webhook Application — in the Node.js SDK that's the AWebhookApplication abstract base class; in PHP it's the WebhookApplicationInterface.

The Subscription Flow #

The user's path through Orchesty is short:

  1. Pick the event in the editor. Drop a Webhook node into a topology, double-click it (or right-click → Pick subscription), and choose <application>.<event> from the search-friendly submenu. The node name is auto-set to that canonical form and is not user-renameable. Save and publish — at this point the schema is purely declarative.
  2. Subscribe on the topology detail. Click Subscribe on the webhook node. A small modal asks for an optional Parameters (JSON object) field. On submit, Orchesty calls the external API on your behalf — "whenever a new Lead is created, send the data to this URL" — captures the resulting webhook id and token, and persists the live registration.
  3. Receive events. The third-party service POSTs to the token-protected URL, the platform routes the payload into the webhook node, and your topology starts the process.
  4. Unsubscribe. One click on the topology detail tells the external API to stop sending data and flips the registration off. Idempotent — clicking it twice is harmless.

3. Triggers: When to Subscribe and Unsubscribe? #

Managing when a webhook is active is a critical architectural decision for any developer.

  • Activation vs. Subscribe. Activating an Application in the Admin UI only provides credentials — that step on its own does not register any webhook. Subscribing is a per-webhook-node action done in the topology detail, so a single Application can have multiple webhook nodes across multiple topologies, each subscribed independently.
  • Cascade on enable / disable. Enabling or disabling a topology cascades to every webhook node it owns. Disable a topology and Orchesty unsubscribes upstream automatically; re-enable and the registrations come back from the persisted intent.
  • Cleanup on deletion. Removing a webhook node from the schema (or deleting the topology) triggers a best-effort unsubscribe upstream. If the unsubscribe fails (network blip, upstream 5xx), the topology detail surfaces an orphan banner with a one-click cleanup action.

Architect's Note: Leaving "ghost" webhooks active on an external server after you've stopped your topology is bad practice. It leads to unnecessary traffic and potential security holes. Orchesty's WebhookManager plus the orphan banner are designed to help you ensure that when the data should stop flowing, the external service is notified immediately.

4. Behind the Scenes: The Webhook Application #

For the developer, transforming a standard app into a Webhook-ready one means extending the right base class — AWebhookApplication in Node.js, WebhookApplicationInterface in PHP — and defining five core responsibilities:

  1. Definitions: Declaring which events are available (e.g., "Invoice Paid", "Contact Updated"), each with an optional human-readable description shown in the editor's webhook picker.
  2. Subscription Request: Building the specific HTTP packet the external API expects for registration.
  3. Unsubscribe Request: Building the packet to cancel the subscription.
  4. Response Handling: Parsing the API's confirmation to save the Webhook ID for future management.
  5. Success Validation: Confirming that the external system successfully removed the hook.

5. The Topology Connection #

A Webhook doesn't exist in isolation. In the visual designer the editor pairs each webhook node with one event from one Application — the chosen event becomes the node's name in the canonical <application>.<event> form and the node is locked to that identity. The platform then routes every inbound payload through the right token-protected URL into that exact node.

This creates a seamless loop: the external system hits the URL → the platform identifies the live subscription → the data is instantly injected into the correct node in your topology.

Summary for the Learn Hub #

  • Proactive Listening: Webhooks eliminate the need for constant "polling" of APIs.
  • Automated Lifecycle: Orchesty handles the registration and deletion of hooks so you don't have to manage them manually in the third-party dashboard.
  • Clean Infrastructure: The orphan banner and the one-click unsubscribe ensure your integrated ecosystem stays free of "ghost" data calls.

For the developer-side reference and the canvas mechanics, see Patterns: Webhooks and Building nodes: Event nodes.