Webhooks

Configure webhook triggers to receive data from external services.

Webhook URL

Each flow with a webhook trigger gets a unique URL:

https://webhook-trigger-worker.<domain>.workers.dev/trigger/<token>

Get your webhook URL:

• In Lux Studio: Select flow → View webhook URL
• Via CLI: lux flow webhook-url <flow-id>

Setting Up Webhooks

1. Create Webhook Trigger

Add a Webhook Trigger node to your flow.

2. Get Your URL

The webhook URL is generated automatically. Copy it from the flow builder or CLI.

3. Configure External Service

Paste the webhook URL in the external service (Stripe, GitHub, etc.).

4. Test the Webhook

Send a test request to verify it works:

curl -X POST https://your-webhook-url \
  -H "Content-Type: application/json" \
  -d '{"test": "data"}'

Webhook Data

Data from webhooks is available in your flow as variables:

Example: Access nested body data:

{{body.customer.email}}
{{body.order.items[0].name}}

Signature Verification

For security, verify webhook signatures from services that support it.

Stripe Example

// In a Code node
const crypto = require('crypto');
const signature = inputs.headers['stripe-signature'];
const payload = JSON.stringify(inputs.body);
const secret = inputs.stripeWebhookSecret;
 
const expectedSig = crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');
 
if (signature !== `sha256=${expectedSig}`) {
  throw new Error('Invalid webhook signature');
}

Webhook Workflow

Use the CLI to set up webhooks interactively:

# 1. Start listening for webhooks
lux flow webhook-listen <flow-id>
 
# 2. Send a test webhook from external service
 
# 3. Check if captured
lux flow webhook-poll <flow-id>
 
# 4. Accept the format (creates schema from payload)
lux flow webhook-accept <flow-id>
 
# 5. Verify
lux flow webhook-url <flow-id>

Responding to Webhooks

Use the Respond node to send a response:

{
  "status": 200,
  "body": {
    "received": true
  }
}

Important: Some services require a response within a timeout (e.g., 10 seconds). For long-running operations:

1. Respond immediately with acknowledgment
2. Process asynchronously
3. Send results via callback or store for polling

Common Webhook Sources

Stripe

• Payment events (succeeded, failed)
• Subscription events (created, cancelled)
• Invoice events

GitHub

• Push events
• Pull request events
• Issue events

Twilio

• SMS received
• Call events
• Voice webhooks

Custom Applications

• Form submissions
• User actions
• System events

Security Best Practices

1. Verify Signatures - Always verify webhook signatures when available
2. Use HTTPS - Webhook URLs use HTTPS by default
3. Validate Payload - Check that required fields are present
4. Idempotency - Handle duplicate deliveries gracefully
5. Timeout Handling - Respond quickly to avoid retries

See Also:

• Triggers
• CLI Webhook Commands