Webhooks

A webhook trigger executes a graph when an external system sends an HTTP POST request to the webhook's unique URL. You can define an optional payload schema to validate incoming requests before the graph runs.

Overview

Webhook triggers connect Swirls to the rest of your stack:

• Event-driven -- Any system that can send HTTP requests can trigger a graph. New ticket, new lead, new order -- each event starts a workflow automatically.
• Schema validation -- Define the expected payload shape so invalid or malformed requests are rejected before execution. See Schemas.
• No polling -- Swirls receives events in real time. You do not need to poll external systems for changes.

Configuration

To set up a webhook trigger:

1. Create a trigger of type webhook in the Portal or via the API. Swirls generates a unique webhook URL for the trigger.
2. Define a payload schema (optional but recommended) so only valid payloads trigger graph execution. See Schemas.
3. Attach the trigger to a root node of your graph. The graph must have a root node (a node with no incoming edges) before a trigger can be attached.

Once configured, the trigger can be enabled or disabled without removing it from the graph. Copy the webhook URL and configure it in your external system.

Sending requests

Send an HTTP POST request to /webhooks/:webhookId with a JSON body. If a payload schema is defined, Swirls validates the request body before starting execution. The response returns message and executionIds confirming that execution has started. Requests that fail validation return errors and do not trigger a graph run.

Security best practices

Webhook URLs are publicly accessible, so take steps to verify that incoming requests are legitimate:

• Signing secrets -- If your provider supports webhook signatures (for example, HMAC), configure the shared secret and validate signatures to confirm the request originated from a trusted source.
• API keys -- Require an API key in request headers to authenticate incoming webhook calls.
• IP allowlisting -- Restrict access to the webhook URL to known IP addresses from your provider.
• Keep secrets out of URLs -- Never embed API keys, tokens, or other secrets in the webhook URL itself.

Use cases

• Customer support -- New ticket from Zendesk or Intercom triggers a triage and routing graph.
• Sales -- New lead from your CRM triggers an enrichment and scoring graph.
• E-commerce -- New order triggers a fulfillment or notification graph.
• CI/CD -- Deployment events trigger monitoring, reporting, or rollback graphs.

Next steps

• Schemas -- Define payload schemas for webhook validation.
• Graphs -- Understand how graphs, root nodes, and execution work.
• Forms -- Use form triggers for structured user input instead of external events.