Webhook Trigger

Receive HTTP POST requests to trigger workflows and integrate with external systems.

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

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.

Method	How it works
No authentication	Webhook is publicly accessible — anyone with the URL can trigger it. Good for testing and low-security use cases.
Header	Send 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 parameter	Send 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.

Advanced options

In Advanced options, turn on the matching option when you need signature headers or the original request body in the workflow. Both options are off by default.

• Include signature headers: Adds the request content type and supported signature headers to the trigger output under headers. Other incoming headers are omitted from the output. This includes signature headers from Stripe, GitHub, Slack, DocuSign, Shopify, Svix, and Standard Webhooks.
• Preserve raw request body: Keeps the original unparsed body in the trigger output under rawBody. Requests using this option are limited to 12 MB because both the parsed and raw body are retained.

Turn both on when a later step must check a provider signature, such as Stripe.

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). Parsing still happens when Preserve raw request body is on. When Include signature headers is on, content type and supported signature headers are also available in the trigger output.
4. Workflow is queued for execution
5. Webhook responds immediately with 202 Accepted
6. Workflow processes asynchronously in the background

headers and rawBody appear on the trigger output only when the matching switch is on for that webhook trigger.

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"}'

Sending Files

Send webhook files as JSON under file for one file or files for up to 20 files. You can use these keys at the top level or inside nested objects.

Each file object requires fileName, mimeType, and one content field. Use base64 for binary files such as XLSX files or text for text files. Keep the full JSON request body below 25 MB, including Base64 encoded content. When Preserve raw request body is on, the request is limited to 12 MB.

{
  "files": [
    {
      "fileName": "quarterly-report.xlsx",
      "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "base64": "UEsDB..."
    }
  ]
}

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

Turn on Include signature headers in the Langdock webhook trigger to receive x-hub-signature-256.

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

Turn on Include signature headers and Preserve raw request body so the Code step can read stripe-signature from trigger.output.headers and the original body from trigger.output.rawBody.

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

Turn on Include signature headers to receive x-slack-signature and x-slack-request-timestamp.

Accessing Webhook Data

Webhook data is separated into body (JSON payload) and query (URL parameters). When the matching Advanced options switch is on, the output also includes headers and/or rawBody.

Request Body

Access JSON payload fields:

{{trigger.output.body.user_id}}
{{trigger.output.body.event_type}}
{{trigger.output.body.data.amount}}

Files

Processed files replace the original file objects in the request body. Access files sent under files in trigger.output.body.files:

{{trigger.output.body.files[0].path}}
{{trigger.output.body.files[0]._metadata.name}}
{{trigger.output.body.files[0]._metadata.mimeType}}

For a file sent under file, use {{trigger.output.body.file.path}}.

Query Parameters

Access URL query parameters:

{{trigger.output.query.param_name}}

Headers

When Include signature headers is on, access the request content type and supported signature headers:

{{trigger.output.headers["content-type"]}}
{{trigger.output.headers["stripe-signature"]}}

Header names in the output are lowercase, such as content-type and stripe-signature. Names that are not supported do not appear.

Raw Body

When Preserve raw request body is on, access the original unparsed body as a string. GET requests set rawBody to an empty string.

{{trigger.output.rawBody}}

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

Code	Meaning	When It Happens
202	Accepted	Workflow queued successfully
400	Bad Request	Invalid workflow ID, format, or secret
404	Not Found	Workflow not found
413	Payload Too Large	Raw body over 12 MB, or combined output over 25 MB
429	Too Many Requests	Rate limit or spending cap reached
500	Server Error	Internal 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

FAQ

How do I trigger a workflow from an external service?

Use a Webhook Trigger when an external service should start a workflow by sending an HTTP request. Configure the external service to call the workflow’s webhook URL with the expected method, headers, and payload.

What should I check if a webhook trigger does not fire?

Check the webhook URL, request method, authentication or signing requirements, payload shape, and whether the external service actually sent the request. Also verify that the workflow is active and that any required fields are present in the incoming payload.