Webhook Integration

Relevant source files

• docs/versioned_docs/version-1.8.0/Develop/environment-variables.mdx
• src/backend/base/langflow/api/build.py
• src/backend/base/langflow/api/v1/base.py
• src/backend/base/langflow/api/v1/callback.py
• src/backend/base/langflow/api/v1/chat.py
• src/backend/base/langflow/api/v1/mcp_utils.py
• src/backend/base/langflow/api/v1/validate.py
• src/backend/base/langflow/base/prompts/api_utils.py
• src/backend/base/langflow/helpers/flow.py
• src/backend/base/langflow/helpers/user.py
• src/backend/base/langflow/services/job_queue/factory.py
• src/backend/base/langflow/services/job_queue/service.py
• src/backend/base/langflow/services/telemetry/opentelemetry.py
• src/backend/tests/unit/api/v1/test_mcp_utils.py
• src/backend/tests/unit/api/v1/test_validate.py
• src/backend/tests/unit/helpers/test_flow_helpers.py
• src/backend/tests/unit/test_chat_endpoint.py
• src/backend/tests/unit/test_endpoints.py
• src/backend/tests/unit/test_redis_job_queue_service.py
• src/backend/tests/unit/test_telemetry.py
• src/backend/tests/unit/test_webhook.py
• src/backend/tests/unit/test_webhook_sse_regression.py
• src/lfx/src/lfx/graph/checkpoint/builder.py
• src/lfx/src/lfx/graph/checkpoint/resume.py
• src/lfx/src/lfx/graph/checkpoint/schema.py
• src/lfx/tests/unit/graph/checkpoint/test_resume_round_trip.py

This document covers the webhook integration system in Langflow, which enables flows to be triggered via external HTTP POST requests. Webhooks provide a fire-and-forget execution pattern with optional real-time event streaming for UI feedback.

Architecture Overview

The webhook system consists of four primary components:

1. Webhook Endpoint (/api/v1/webhook/{flow_id_or_name}) - Accepts HTTP POST requests and triggers asynchronous flow execution src/backend/tests/unit/test_webhook.py20-31
2. SSE Events Endpoint (/api/v1/webhook-events/{flow_id_or_name}) - Streams real-time execution updates to connected UI clients. This endpoint requires proper authentication (API key or session cookie) src/backend/tests/unit/test_webhook_sse_regression.py1-22
3. Webhook Components - Special flow components that receive and process incoming HTTP request data. The backend identifies these via get_all_webhook_components_in_flow src/backend/base/langflow/services/database/models/flow/utils.py73
4. Event Manager (WebhookEventManager) - Manages the delivery of tokens and build updates during execution src/backend/base/langflow/services/event_manager.py7

System Architecture

The following diagram illustrates the interaction between the FastAPI router, the authentication service, and the background task execution.

Sources: src/backend/base/langflow/api/v1/chat.py114-115 src/backend/base/langflow/api/build.py19-28 src/backend/base/langflow/services/event_manager.py85 src/backend/tests/unit/test_webhook.py20-31

Webhook Endpoint

Route Definition and Response

The main webhook endpoint is defined at /api/v1/webhook/{flow_id_or_name} and returns 202 ACCEPTED immediately without waiting for flow completion src/backend/tests/unit/test_webhook.py20-31

The flow_id_or_name parameter accepts either:

• Flow UUID: A standard unique identifier src/backend/tests/unit/test_webhook.py33-42
• Endpoint Name: A human-readable alias resolved via get_flow_by_id_or_endpoint_name src/backend/base/langflow/helpers/flow.py56

Sources: src/backend/tests/unit/test_webhook.py20-42 src/backend/base/langflow/helpers/flow.py56

Request Processing Flow

The sequence diagram below details the internal logic of the webhook execution and its delegation to background tasks.

The endpoint processes requests through the following steps:

1. Flow Resolution: The system identifies the flow using get_flow_by_id_or_endpoint_name src/backend/base/langflow/helpers/flow.py56
2. User Authentication: Validates the credentials via api_key_security src/backend/base/langflow/services/auth/utils.py61
3. Body Extraction: Reads the HTTP request body via parse_input_request_from_body, which supports both application/json and multipart/form-data src/backend/base/langflow/api/v1/chat.py400-430
4. Start Flow Build: Calls start_flow_build to initiate the flow execution as a background job src/backend/base/langflow/api/v1/chat.py432 This function registers the job owner with the JobQueueService src/backend/base/langflow/api/v1/chat.py95-111
5. Immediate Response: Returns 202 ACCEPTED with status "in progress" src/backend/tests/unit/test_webhook.py28-30

Sources: src/backend/base/langflow/api/v1/chat.py95-111 src/backend/base/langflow/api/v1/chat.py400-430 src/backend/base/langflow/api/v1/chat.py432 src/backend/base/langflow/services/auth/utils.py61 src/backend/tests/unit/test_webhook.py20-31 src/backend/base/langflow/helpers/flow.py56

Authentication Modes

Configuration-Based Authentication

Webhook authentication is controlled by the WEBHOOK_AUTH_ENABLE setting. This setting defaults to True for "secure-by-default" behavior src/backend/tests/unit/test_webhook.py168-171

Mode	WEBHOOK_AUTH_ENABLE	Behavior
Owner Mode	false	Executes without requiring an API key src/backend/tests/unit/test_webhook.py145-164
API Key Mode	true (Default)	Requires a valid API key; otherwise returns 403 Forbidden src/backend/tests/unit/test_webhook.py60-81

Sources: src/backend/tests/unit/test_webhook.py60-81 src/backend/tests/unit/test_webhook.py145-171

SSE Event Delivery

To enable real-time UI updates for background webhook tasks, the system provides an SSE endpoint at /api/v1/webhook-events/{flow_id}.

• Authentication Requirements: The SSE endpoint requires a valid API key or session, verified via get_current_user_for_sse src/backend/base/langflow/services/auth/utils.py63
• Event Emission: During execution, the graph engine calls emit_vertex_build_event to push updates to the webhook_event_manager src/lfx/src/lfx/graph/utils.py123-202
• Payload Details: Events include build_start and end_vertex, providing duration, build results, outputs, and artifacts serialized via serialize_for_json src/lfx/src/lfx/graph/utils.py151-202

Sources: src/lfx/src/lfx/graph/utils.py123-228 src/backend/base/langflow/services/auth/utils.py63

Configuration Reference

Variable	Default	Description
LANGFLOW_WEBHOOK_AUTH_ENABLE	true	Enable API key authentication for webhook endpoints src/backend/tests/unit/test_webhook.py168-171
SSE_HEARTBEAT_TIMEOUT_SECONDS	10.0	Interval (seconds) at which the streaming response's heartbeat refreshes the polling-watchdog activity key src/backend/base/langflow/api/build.py56

Sources: src/backend/tests/unit/test_webhook.py168-171 src/backend/base/langflow/api/build.py56