Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.langdock.com/llms.txt

Use this file to discover all available pages before exploring further.

Webhook Trigger

​
Overview

The Webhook Trigger provides a unique HTTP endpoint that external systems can call to start your workflow. It’s the bridge between Langdock Workflows and any external service or application that can send HTTP requests.
Best for: Real-time integrations, external system events, API-driven workflows, and connecting services without native integrations.

​
When to Use Webhook Trigger

Perfect for:
  • Receiving events from external services (GitHub, Stripe, custom apps)
  • Real-time data processing from external systems
  • Building custom integrations
  • Connecting services that support webhooks (including other workflows)
  • API-driven workflows initiated by other systems
Not ideal for:
  • User-facing data collection (use Form Trigger)
  • Scheduled recurring tasks (use Scheduled Trigger)
  • Native integration events (use Integration Trigger)

​
Configuration

​
Basic Setup

Webhook Trigger When you add a Webhook Trigger, you automatically get:
  • Unique Webhook URL: A secure endpoint for receiving requests
  • Webhook ID: Identifier for your webhook

​
Security Options

Use the Authentication method setting to control how your webhook is secured. When you select an auth method, a secret is auto-generated for you. The secret is preserved when you switch between methods, so you won’t accidentally lose your configured key.
MethodHow it works
No authenticationWebhook is publicly accessible — anyone with the URL can trigger it. Good for testing and low-security use cases.
HeaderSend the secret via the X-Webhook-Secret HTTP header. The webhook URL stays clean; the UI shows a curl snippet with the header included.
Query parameterSend the secret as ?secret=... appended to the URL. This is the legacy behavior and remains fully supported.
A secret is required whenever an auth method is selected. Leaving the secret field empty while an auth method is active will show a validation warning. Best Practice: Always use a secret for production webhooks to prevent unauthorized access. Header-based auth is preferred as it keeps secrets out of server logs and browser history.
Existing webhooks that use a query parameter secret continue to work without any changes. The authentication method field is optional — if unset, the old behavior is preserved automatically.

​
How It Works

  1. External system sends HTTP POST request to webhook URL
  2. Webhook validates secret (if configured, via X-Webhook-Secret header or ?secret= query parameter)
  3. Request payload is parsed (JSON body and query parameters)
  4. Workflow is queued for execution
  5. Webhook responds immediately with 202 Accepted
  6. Workflow processes asynchronously in the background
Webhooks always process asynchronously. The webhook responds immediately with 202 Accepted while the workflow runs in the background.

​
Making Requests to Your Webhook

​
Basic Request

# No authentication
curl -X POST https://app.langdock.com/api/hooks/workflows/YOUR_WORKFLOW_ID \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

# Header authentication (recommended)
curl -X POST https://app.langdock.com/api/hooks/workflows/YOUR_WORKFLOW_ID \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: YOUR_SECRET" \
  -d '{"key": "value"}'

# Query parameter authentication (legacy)
curl -X POST "https://app.langdock.com/api/hooks/workflows/YOUR_WORKFLOW_ID?secret=YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

​
Example Use Cases

​
GitHub Webhook Integration

Webhook Trigger (GitHub push events)
→ Agent: Analyze commit messages
→ Condition: Check if documentation updated
  → Yes: Regenerate docs
  → No: Continue
→ Notification: Send deployment status
GitHub Webhook Configuration:
  • URL: Your webhook URL
  • Events: Push, Pull Request
  • Content type: application/json

​
Stripe Payment Webhook

Webhook Trigger (Stripe events)
→ Code: Validate Stripe signature
→ Condition: Check event type
  → payment_succeeded: Update user account
  → payment_failed: Send retry notification
  → subscription_canceled: Deactivate access

​
Custom Application Integration

Webhook Trigger
→ Code: Validate and transform data
→ HTTP Request: Enrich data from external API
→ Agent: Analyze and categorize
→ Action: Create record in CRM

​
Slack Command Integration

Webhook Trigger (from Slack slash command)
→ Agent: Process natural language command
→ HTTP Request: Execute action in external system
→ HTTP Response: Send result back to Slack

​
Accessing Webhook Data

Webhook data is separated into body (JSON payload) and query (URL parameters):

​
Request Body

Access JSON payload fields: 
{{trigger.output.body.user_id}}
{{trigger.output.body.event_type}}
{{trigger.output.body.data.amount}}

​
Query Parameters

Access URL query parameters: 
{{trigger.output.query.param_name}}

​
Example

For a request like: 
POST /api/hooks/workflows/abc123?source=github
Body: {"event": "push", "repo": "my-repo"}
Access the data: 
Source: {{trigger.output.query.source}}
Event: {{trigger.output.body.event}}
Repo: {{trigger.output.body.repo}}

​
Response Codes

CodeMeaningWhen It Happens
202AcceptedWorkflow queued successfully
400Bad RequestInvalid workflow ID, format, or secret
404Not FoundWorkflow not found
429Too Many RequestsRate limit or spending cap reached
500Server ErrorInternal error processing webhook

​
Next Steps

Integration Trigger

Use native integration events

HTTP Request Node

Make requests to external APIs

Code Node

Validate and transform webhook data

Getting Started

Build your first workflow