Webhook Triggers

Webhook triggers allow external services to trigger your trigger chains by sending an HTTP request to RTILA X. Instead of running a chain manually or on a schedule, an external service (like Zapier, Make.com, a custom script, or another application) can send a POST request to a specific URL, and RTILA X will execute the trigger chain automatically.

This turns RTILA X into a webhook receiver — any service that can send an HTTP POST request can trigger your automation pipelines.

New in v8.3.2: Webhook triggers are part of the new Trigger Chains system. Previous versions of RTILA X did not support webhook-triggered pipelines.

Webhook flow diagram showing an external service sending a POST request to RTILA X which triggers a chain

How Webhook Triggers Work

Here’s the complete flow of a webhook-triggered chain:

External service sends a request. A service like Zapier, Make.com, or a custom script sends an HTTP POST request to your RTILA X webhook URL.
RTILA X receives the request. The webhook receiver endpoint processes the incoming request.
Authentication is verified. RTILA X checks the X-Api-Key header against the chain’s API key.
Signature is verified (if configured). If a webhook secret is set, RTILA X verifies the X-Webhook-Signature header.
The chain is validated. RTILA X checks that the chain exists, is active, and has remote execution enabled.
A run is created. A new trigger chain run record is created with triggered_by: "webhook".
The job is queued. A queue record is created and the relay engine picks it up.
A response is returned. RTILA X returns a 202 Accepted response with the run ID and queue ID.

The Webhook Endpoint

Endpoint URL

POST /api/rtila/webhook/{chain_id}

Replace {chain_id} with the ID of your trigger chain. You can find the chain ID in the Trigger Chains list or in the chain’s URL.

Full URL Example

If your RTILA X instance is running at http://192.168.1.100:8880 and your chain ID is abc123def456, the full webhook URL is:

POST http://192.168.1.100:8880/api/rtila/webhook/abc123def456

If you’re using a public tunnel, the URL would be:

POST https://random-xyz.trycloudflare.com/api/rtila/webhook/abc123def456

Required Headers

Header	Required	Description
`Content-Type`	✅ Yes	Must be `application/json`
`X-Api-Key`	✅ Yes (if chain has API key)	The chain’s API key for authentication
`X-Webhook-Signature`	✅ Yes (if webhook secret is set)	HMAC-SHA256 signature of the request body

Request Body

The request body must be valid JSON. The primary field is input_payload, which contains the data you want to pass to the trigger chain:

{
  "input_payload": {
    "key1": "value1",
    "key2": "value2",
    "data": [1, 2, 3]
  }
}

Field	Type	Required	Description
`input_payload`	Object	No	The data to pass to the trigger chain. Can contain any JSON data.

Note: The input_payload is optional. If you don’t include it, the chain will run without any input data. However, if your chain’s triggers expect input data (e.g., via ${input_payload.key}), you should include it.

Authentication

API Key Authentication

Every trigger chain can have an API key that authenticates webhook requests. When a webhook request arrives, RTILA X checks the X-Api-Key header against the chain’s stored API key.

Header	Value	Description
`X-Api-Key`	The chain’s API key	Must match exactly

If the API key doesn’t match, RTILA X returns a 401 Unauthorized response:

{
  "error": "Invalid API key"
}

Getting Your Chain’s API Key

Go to Trigger Chains in the sidebar.
Select the trigger chain.
Click Remote in the ribbon toolbar.
Toggle Enable Remote Execution to On.
An API key is generated automatically.
Copy the API key.

Tip: You can regenerate the API key at any time by clicking Generate New Key in the Remote Execution dialog. This immediately invalidates the old key.

Webhook Signature Verification

For additional security, you can configure a webhook secret on your trigger chain. When a webhook secret is set, RTILA X verifies the X-Webhook-Signature header on every incoming request.

How Signature Verification Works

The external service computes an HMAC-SHA256 hash of the raw request body using the webhook secret.
The hash is sent in the X-Webhook-Signature header.
RTILA X computes its own HMAC-SHA256 hash of the received request body using the stored webhook secret.
RTILA X compares the two hashes using a timing-safe comparison (to prevent timing attacks).
If the hashes match, the request is accepted. If they don’t match, the request is rejected with a 401 error.

Computing the Signature

To compute the signature, use HMAC-SHA256:

signature = HMAC-SHA256(webhook_secret, raw_request_body)

The signature should be sent as a hexadecimal string in the X-Webhook-Signature header.

Example: Computing the Signature in Python

import hmac
import hashlib
import json

webhook_secret = "your-webhook-secret"
body = json.dumps({"input_payload": {"key": "value"}})

signature = hmac.new(
    webhook_secret.encode('utf-8'),
    body.encode('utf-8'),
    hashlib.sha256
).hexdigest()

print(f"X-Webhook-Signature: {signature}")

Example: Computing the Signature in JavaScript (Node.js)

const crypto = require('crypto');

const webhookSecret = 'your-webhook-secret';
const body = JSON.stringify({ input_payload: { key: 'value' } });

const signature = crypto
  .createHmac('sha256', webhookSecret)
  .update(body)
  .digest('hex');

console.log(`X-Webhook-Signature: ${signature}`);

Setting Up a Webhook Secret

Go to Trigger Chains in the sidebar.
Select the trigger chain.
Click Builder in the ribbon toolbar.
Click the Start Node (the first node in the flow).
In the Chain Settings panel, find the Webhook Secret field.
Enter your webhook secret (any random string).
Click Save.

Tip: Use a long, random string as your webhook secret. For example: whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6. The longer and more random the secret, the more secure your webhook.

When to Use a Webhook Secret

Scenario	Use Webhook Secret?
Public-facing webhook (accessible from the internet)	✅ Yes — always
Internal webhook (only accessible from your network)	Recommended
Testing locally	Optional
High-security applications	✅ Yes — always

Response Format

Successful Response (202 Accepted)

When a webhook request is accepted, RTILA X returns a 202 Accepted response:

{
  "run_id": "run_abc123def456",
  "queue_id": "queue_ghi789jkl012",
  "status": "queued"
}

Field	Type	Description
`run_id`	String	The ID of the trigger chain run that was created
`queue_id`	String	The ID of the queue record that was created
`status`	String	Always `"queued"` for a successful webhook trigger

Error Responses

Status Code	Error	Cause	Solution
`400`	`"Missing chain_id"`	The chain ID is missing from the URL	Include the chain ID in the URL path
`400`	`"Content-Type must be application/json"`	Wrong Content-Type header	Set `Content-Type: application/json`
`400`	`"Invalid JSON body"`	The request body is not valid JSON	Check your JSON syntax
`400`	`"Webhook payload is required"`	The request body is empty	Include a JSON body (even if empty: `{}`)
`401`	`"Invalid API key"`	The `X-Api-Key` header doesn’t match	Check your API key
`401`	`"Invalid webhook signature"`	The `X-Webhook-Signature` doesn’t match	Check your webhook secret and signature computation
`403`	`"Trigger chain is not active"`	The chain has status “draft” or “paused”	Set the chain status to “active”
`403`	`"Remote execution is disabled for this chain"`	Remote execution is not enabled	Enable remote execution in the chain’s Remote settings
`404`	`"Trigger chain not found"`	The chain ID doesn’t exist	Check the chain ID
`409`	`"A job for this trigger chain is already running or pending."`	The chain already has a running or pending job	Wait for the current run to complete

Setting Up a Webhook Trigger

Step-by-Step Guide

Create or select a trigger chain.
- Go to Trigger Chains in the sidebar.
- Select an existing chain or create a new one.
Set the chain status to “active.”
- Open the chain in the Builder.
- In the Chain Settings panel, set the status to “Active.”
Enable remote execution.
- Go back to the Trigger Chains list.
- Select the chain.
- Click Remote in the ribbon.
- Toggle Enable Remote Execution to On.
- Copy the generated API key.
Optionally set a webhook secret.
- Open the chain in the Builder.
- Click the Start Node.
- Enter a webhook secret in the Chain Settings panel.
- Save the chain.
Find your webhook URL.
- The webhook URL is: http://YOUR_RTILA_URL/api/rtila/webhook/{chain_id}
- If using a public tunnel: https://YOUR_TUNNEL_URL/api/rtila/webhook/{chain_id}
Configure the external service.
- In Zapier, Make.com, or your custom script, set up a webhook/HTTP POST action.
- Set the URL to your webhook URL.
- Set the method to POST.
- Set the Content-Type header to application/json.
- Set the X-Api-Key header to your chain’s API key.
- If using a webhook secret, set the X-Webhook-Signature header.
- Set the body to your JSON payload.
Test the webhook.
- Send a test request.
- Check the response.
- Verify the chain run was created.

Testing with curl

Basic Webhook Request (No Signature)

curl -X POST 'http://192.168.1.100:8880/api/rtila/webhook/abc123def456' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: your-api-key-here' \
  -d '{
    "input_payload": {
      "source": "zapier",
      "event": "new_order",
      "order_id": "12345"
    }
  }'

Webhook Request with Signature

First, compute the signature:

# Compute the HMAC-SHA256 signature
BODY='{"input_payload":{"source":"zapier","event":"new_order"}}'
SECRET="your-webhook-secret"
SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

# Send the request
curl -X POST 'http://192.168.1.100:8880/api/rtila/webhook/abc123def456' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: your-api-key-here' \
  -H "X-Webhook-Signature: $SIGNATURE" \
  -d "$BODY"

Webhook Request via Public Tunnel

curl -X POST 'https://random-xyz.trycloudflare.com/api/rtila/webhook/abc123def456' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: your-api-key-here' \
  -d '{"input_payload": {"test": true}}'

Expected Successful Response

{
  "run_id": "run_abc123def456",
  "queue_id": "queue_ghi789jkl012",
  "status": "queued"
}

Testing Error Cases

Test invalid API key:

curl -X POST 'http://192.168.1.100:8880/api/rtila/webhook/abc123def456' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: wrong-key' \
  -d '{}'

Expected response: 401 with {"error": "Invalid API key"}

Test missing Content-Type:

curl -X POST 'http://192.168.1.100:8880/api/rtila/webhook/abc123def456' \
  -H 'X-Api-Key: your-api-key-here' \
  -d '{}'

Expected response: 400 with {"error": "Content-Type must be application/json"}

Test invalid chain ID:

curl -X POST 'http://192.168.1.100:8880/api/rtila/webhook/nonexistent-id' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: your-api-key-here' \
  -d '{}'

Expected response: 404 with {"error": "Trigger chain not found"}

Using Webhooks with Zapier

In Zapier, create a new Zap.
Set up your trigger (e.g., “New Email”, “New Form Submission”).
Add an action step: Webhooks by Zapier → POST.
Set the URL to your webhook URL.
Set the Method to POST.

Set the Data to your JSON payload:

{
  "input_payload": {
    "field1": "{{field1}}",
    "field2": "{{field2}}"
  }
}

Add headers:
- Content-Type: application/json
- X-Api-Key: Your chain’s API key
Test the Zap.
Turn on the Zap.

Using Webhooks with Make.com (Integromat)

In Make.com, create a new scenario.
Add your trigger module.
Add an action module: HTTP → Make a request.
Set the URL to your webhook URL.
Set the Method to POST.
Set the Body type to Raw and content type to JSON.
Enter your JSON payload.
Add headers:
- Content-Type: application/json
- X-Api-Key: Your chain’s API key
Test the scenario.
Turn on the scenario.

Security Best Practices

Practice	Why It Matters
Always use a webhook secret for public-facing webhooks	Prevents unauthorized requests from triggering your chains
Use long, random webhook secrets	Short secrets can be brute-forced
Regenerate API keys periodically	Reduces the risk of compromised keys
Use HTTPS for public webhooks	Encrypts the request in transit. Use the public tunnel for HTTPS.
Monitor webhook activity	Check the trigger chain runs page for unexpected webhook-triggered runs
Use different API keys for different chains	Limits the impact if one key is compromised
Don’t share API keys in plain text	Store them in your service’s secret management system
Use the timing-safe comparison	RTILA X uses timing-safe comparison internally. Don’t implement your own.

Troubleshooting

Problem	Cause	Solution
`401 Invalid API key`	Wrong API key in the request	Double-check the API key in the Remote Execution dialog
`401 Invalid webhook signature`	Signature doesn’t match	Verify your webhook secret and signature computation. Make sure you’re hashing the exact raw body.
`403 Trigger chain is not active`	Chain status is not “active”	Set the chain status to “active” in the Builder
`403 Remote execution is disabled`	Remote execution is not enabled	Enable remote execution in the Remote Execution dialog
`404 Trigger chain not found`	Wrong chain ID in the URL	Verify the chain ID
`409 Already running or pending`	Chain already has a running job	Wait for the current run to complete before triggering again
`400 Invalid JSON body`	Malformed JSON	Check your JSON syntax. Use a JSON validator.
Connection refused	RTILA X is not running or the URL is wrong	Verify RTILA X is running and the URL is correct
Timeout	Network issue or RTILA X is overloaded	Check your network connection and RTILA X status