Webhook Trigger System#

Dify's webhook trigger system lets external HTTP clients drive workflow execution. When a Webhook Trigger node is placed at the root of a Workflow app, Dify assigns it a unique, publicly reachable URL. Incoming requests are validated, parameters extracted into typed workflow variables, and execution enqueued asynchronously via Celery — while the caller immediately receives the configured HTTP response.

Scope constraints:

• Available only for Workflow applications (not Chatbot / Chatflow) 1
• Maximum 5 webhook trigger nodes per workflow 2

Architecture#

External HTTP Request
        │
        ▼
 Flask Controller (/triggers/webhook/<id> | /triggers/webhook-debug/<id>)
        │
        ▼
 WebhookService (extract → validate → type-coerce → build inputs)
        │ async via Celery
        ▼
 TriggerWebhookNode (ROOT node; reads variable pool → typed output vars)

Request Lifecycle#

1. Lookup & gate-check — get_webhook_trigger_and_workflow() 4 resolves the WorkflowWebhookTrigger DB record, verifies the linked AppTrigger is ENABLED (raises QuotaExceededError if RATE_LIMITED), and fetches the published Workflow and its node config.

2. Content-length guard — Requests exceeding dify_config.WEBHOOK_REQUEST_BODY_MAX_SIZE are rejected 413 Payload Too Large before any body parsing.

3. Extraction — extract_webhook_data() routes body parsing by content-type:

   • application/json → orjson parse
   • application/x-www-form-urlencoded → request.form dict
   • multipart/form-data → form fields + file uploads via ToolFileManager
   • application/octet-stream → binary saved as a tool file; MIME detected via python-magic
   • text/plain / unknown → raw string under key raw

4. Validation — HTTP method and content-type are checked by _validate_http_metadata(); required headers by _validate_required_headers(); required query/body params during _process_parameters().

5. Type coercion — Form-data string values are cast to Number, Boolean, etc. via _convert_form_value(); JSON values are validated in-place via _validate_json_value().

6. Async dispatch — trigger_workflow_execution() reserves a trigger quota, creates/fetches an EndUser of type TRIGGER, and calls AsyncWorkflowService.trigger_workflow_async(). Quota is refunded on failure.

7. Synchronous response — generate_webhook_response() reads the node's configured status_code (default 200) and response_body and returns immediately. The workflow executes asynchronously.

Node Configuration & Parameter Extraction#

Node settings are governed by the WebhookData Pydantic model:

Inside TriggerWebhookNode._run(), the node reads all pre-injected variables from the variable pool via get_by_prefix(self.id), then calls _extract_configured_outputs() which:

• Strips headers case-insensitively and normalizes hyphens to underscores.
• Reads query params from webhook_data["query_params"].
• For text/plain, wraps the raw string in the configured variable.
• For application/octet-stream, builds a FileVariable.
• For structured bodies, resolves each body param by name; file-type params become FileVariable objects.
• Always outputs _webhook_raw — the full raw webhook_data dict — for debugging.

Default node config for new nodes is defined in get_default_config() with async mode enabled and a 30-second timeout.

Webhook Lifecycle Management#

ID & URL Generation#

Each webhook trigger node receives a unique 24-character URL-safe random ID from generate_webhook_id(). The WorkflowWebhookTrigger DB record has unique constraints on both (app_id, node_id) and webhook_id 5.

Sync on Draft Save#

When a workflow draft is saved, the app_draft_workflow_was_synced signal fires sync_webhook_when_app_created.py 6, which calls WebhookService.sync_webhook_relationships() with remove_stale=False. This method diffs the graph's webhook node IDs against DB records — creating rows for new nodes but preserving stale records from deleted nodes — using a Redis-backed cache (TTL 1 hour) and distributed lock to reduce DB churn. Stale records are preserved so undo operations can restore webhook trigger nodes without changing their URLs.

Sync on Publish#

When a workflow is published, the app_published_workflow_was_updated signal fires the handle_published() event handler, which calls WebhookService.sync_webhook_relationships() with remove_stale=True. At this point, stale webhook records — those corresponding to deleted nodes — are actually deleted from the database along with their Redis cache entries. This two-phase approach (preserve on draft, cleanup on publish) ensures undo operations work correctly while eventually removing obsolete webhook URLs once changes are published.

Debug vs. Production#

The debug endpoint (/webhook-debug/<id>) resolves the draft workflow, skips quota checks and Celery enqueueing, and instead fires a WebhookDebugEvent via TriggerDebugEventBus to the Variable Inspector. If no listener is registered, it returns 409 Conflict.

Frontend URL Registration#

When a TriggerWebhook node is added or changed in the workflow editor, the useAutoGenerateWebhookUrl hook 7 calls fetchWebhookUrl() to register the URL and stores webhook_url / webhook_debug_url on the node. It skips re-generation if URLs already exist (idempotent).

Undo/Redo Behavior#

The workflow history system 8 tracks NodeAdd / NodeDelete events and restores full graph state on undo/redo, but has no webhook-specific backend sync callbacks. When a webhook node add is undone, the frontend removes the node from the graph but the backend WorkflowWebhookTrigger record created by useAutoGenerateWebhookUrl is not deleted. Because draft saves preserve stale webhook records (remove_stale=False), redoing the node add will restore the original webhook URL. Cleanup of stale records only happens during publish operations via the handle_published() event handler.

Quota Enforcement#

Trigger quota is reserved before dispatch. On exhaustion, AppTriggerService.mark_tenant_triggers_rate_limited() sets the tenant's triggers to RATE_LIMITED, causing all subsequent production webhook requests for that tenant to return 429 Too Many Requests.