Webhooks

Introduction

Webhooks are a way to trigger your flows automatically when an event occurs in an external application. Unlike scheduled triggers (which run every X minutes), webhooks fire in real-time — the instant the external application sends data to a URL generated by IONFLOW.

They’re ideal for scenarios where you need to react immediately: a new order in your online store, a completed form, a received payment, or any event an app can notify about.

Who This Section Is For

• Operators: Who need to connect external events with their flows
• Developers: Who integrate their own systems with IONFLOW via HTTP
• Process specialists: Who design reactive, real-time automations

What is a Webhook?

A webhook is a unique URL generated by IONFLOW that waits to receive data (payload) from an external application. When that URL receives an HTTP request, the associated flow executes automatically using the received data.

Key characteristics:

• Each webhook generates a unique URL you can copy and configure in the external app
• Accepts data in the HTTP request body
• Can be configured to accept different HTTP methods (POST, GET, etc.)
• Triggers the flow immediately when it receives data

How Webhooks Work in IONFLOW

IONFLOW has two nodes dedicated to webhooks:

Node (UI Label)	Description
Webhook	Trigger node that generates a URL and activates the flow when it receives data. JSON: ion.trigger.webhook
Webhook Response	Action node that sends a custom response to the service that fired the webhook. JSON: ion.action.webhook_response

Typical Flow

[External app sends POST] → [Webhook receives data] → [Process data] → [Webhook Response sends result]

Creating a Webhook

1. Open a board in the visual editor
2. Drag the Webhook node onto the canvas as your flow’s trigger
3. Click the node to see its configuration
4. Copy the generated URL — this is the URL you’ll configure in your external application
5. Connect the Webhook node to your action nodes
6. Save the board with Commit
7. Activate the board (toggle ON) so the webhook starts listening

Webhook URL

The generated URL has a format similar to:

https://your-instance.ionflow.io/webhook/{webhook_id}

This URL is unique per Webhook node and stays the same as long as the webhook exists. Copy it and configure it in your external application as the notification destination.

Payloads (Received Data)

Data sent to the webhook is available in the node’s output. You can access:

• Body: The HTTP request body (typically JSON)
• Headers: The HTTP request headers
• Query parameters: Parameters in the URL

Example received JSON payload:

{
  "event": "order.created",
  "order_id": "12345",
  "customer": {
    "name": "John Smith",
    "email": "[email protected]"
  },
  "total": 150.00
}

You can reference this data in subsequent nodes using the context system: {{$1.body.customer.name}}

Webhook Responses

The Webhook Response node lets you send a custom response back to the service that fired the webhook. This is useful when the external application expects a confirmation:

• Status code: HTTP response code (200, 201, 400, etc.)
• Body: Response data (JSON, text, etc.)
• Headers: HTTP response headers

If you don’t use a Webhook Response node, IONFLOW automatically responds with a 200 OK.

Webhook Security

To protect your webhooks from unauthorized requests:

• Secret URL: The webhook URL contains a unique, hard-to-guess ID
• Payload validation: You can add validation nodes (Simple Decision) to verify the structure of received data
• HTTPS: All webhook URLs use HTTPS by default

Testing Webhooks

To test your webhook before connecting the external app:

1. Copy the webhook URL
2. Use a tool like curl, Postman, or Insomnia to send a test request:

curl -X POST https://your-instance.ionflow.io/webhook/{webhook_id} \
  -H "Content-Type: application/json" \
  -d '{"test": "sample data", "number": 42}'

3. Check in the visual editor (Dev mode) or execution history that the data arrived correctly

Webhooks vs Other Triggers

Trigger Type	When to Use
Webhook	When you need to react in real-time to external events
Scheduler	When you need to run something periodically (every 5 min, every hour, etc.)
Manual	When the user starts execution from the interface
On Call Component-Flow Trigger	When another flow calls this one as a component

Common Errors

Error	Cause	Solution
”Webhook not receiving data”	Board inactive or wrong URL	Verify the board is active (toggle ON) and the copied URL is correct
”Empty payload”	External app isn’t sending body, or wrong Content-Type	Verify the request includes Content-Type: application/json header and data in the body
”Timeout”	Flow takes longer than expected to respond	Make sure the Webhook Response node is connected and the flow responds quickly
”URL not working”	Webhook was deleted or board was recreated	Generate a new webhook and update the URL in the external app

Key Terms

• Webhook: URL that receives data from external applications and triggers a flow
• Payload: Data sent in the HTTP request body
• Webhook Response: Response sent back to the application that fired the webhook
• Endpoint: The specific URL where requests are received
• HTTP POST: Most common method for sending data to a webhook

Next Steps

• Boards - Design flows with webhooks as triggers
• Connections - Connect apps that fire webhooks
• Integrations - Configure advanced webhooks with custom APIs

See Also

• Boards
• Executions
• Integrations