How the Dify Human Input node adds human approval to AI workflows
The Dify Human Input node adds a pause for a named person to a Dify workflow. When the workflow reaches the node, it stops and delivers a request form either through the Dify web app or by email, and it resumes on the first response. According to the Dify docs, email recipients need no Dify account, and the request closes after that first response, so the node suits a single accountable decision rather than open-ended collaboration. Your team decides whether the reviewer is a workspace member, an external address or the whole workspace, and that choice determines who can act on a request.
Regulated teams usually need this node where an AI output would otherwise trigger a consequential action: a credit or claims recommendation, a customer communication, a change to a record or a release of sensitive content. In those cases the question for an auditor is not only whether a person reviewed the output, but whether the workflow kept a record of who decided, what they saw and which branch the decision selected. Before relying on the node, confirm with your compliance owner which decisions must be recorded, how long those records must be kept and whether your identity provider must be the source of reviewer identity.
This section describes what the node does according to the Dify docs. It does not claim that the node satisfies any specific regulation, control framework or audit requirement, and it does not describe how an independent assessor would judge the evidence. Behavior such as timeout handling, decision routing and the restrictions on web app delivery in trigger-started workflows should be tested in your own environment and against the Dify version you run, because the node's details can change between releases. Treat the Dify docs as the reference for configuration, and treat your own test results as the evidence you bring to a review.
Delivery channels, decision buttons and timeout options compared
This table compares the ways a Human Input node can reach a reviewer, how decision buttons route the workflow, and how timeouts behave when nobody responds. Read each row against your review process: who must be able to respond, whether the reviewer will sit inside Dify, and what should happen if the request stalls.
| Option | What it does | Trade-off | Fit for review processes |
|---|---|---|---|
| Web app to workspace members | Form appears in the Dify web app for members of the workspace | Reviewer needs a Dify account and workspace access | Internal reviewers who already work in Dify and whose access you govern through workspace roles |
| Email to workspace members | Form link sent by email to members of the workspace | Reviewer still needs a Dify account to act on the form | Internal approvers who work mostly from email but already hold accounts |
| Email to external addresses | Form link sent by email to addresses you specify | Recipients need no Dify account, so identity rests on the email link and your own controls | Customers, partners or auditors who must respond once without onboarding; confirm how you verify who opened the link |
| Email to whole workspace | Form link sent to every workspace member | Broad distribution; the request closes after the first response, so any member can decide | Low-risk notifications where any qualified member may act; avoid for high-value approvals |
| Decision buttons | Each button has a title and action ID exposed as __action_id and __action_value for downstream routing | Routing depends on button IDs you define and branch on, so naming must stay stable across edits | Approve, reject or escalate paths that must branch cleanly in the workflow |
| Form fields as variables | Submitted field values become workflow variables | Reviewer input is only as trustworthy as the form design and the channel that delivered it | Capturing a reason, a reference or a comment that the audit trail should keep |
| Timeout strategy | Defines how long the workflow waits and what happens without a response | Long waits hold a paused run; a default path must be safe to take without a human decision | Time-bound reviews where silence should trigger escalation or a safe default rather than an automatic approval |
| Web app in trigger-started workflows | Web app delivery of the form is not available when a trigger starts the workflow | Trigger-started runs must use email delivery instead; confirm current behavior in the Dify docs for your version | Event-driven approvals, such as those from webhooks, that need email delivery |
Where a human review step fits in regulated processes
A Human Input node suits any workflow where an automated step should stop before a decision is acted on. The patterns below differ in who reviews, what they see and where the decision goes next, but each one pauses the run, captures a response and resumes on a named branch.
Credit decision referral
A model drafts a credit recommendation from application data and retrieved policy text. The reviewer sees the draft, the cited policy passages and the input fields, then selects an approve, decline or refer button. Each button's action ID routes the run, and any override reason typed into a form field becomes a workflow variable that downstream nodes can store. Confirm with your credit risk team which fields the reviewer must see and whether the model output is shown at all.
Claims exception review
Claims that fall outside automated thresholds pause for an adjuster. The form asks for a reason code and a free-text justification, and the timeout strategy decides what happens if no one responds. Plan a fallback branch, such as escalation to a supervisor or return to a queue, because a timeout without a defined path leaves cases open. Ask your claims leadership how long a case may wait before escalation applies.
Customer content release
Marketing or support teams use a model to draft customer-facing text. A content owner receives an email with the draft and approve or reject buttons, and the email recipient does not need a Dify account. Because the request closes after the first response, agree in advance who the recipients are and whether a shared mailbox is acceptable for your review rules.
Data access request approval
A workflow collects an access request, checks the requester's role against a document, and sends it to the data owner. The form captures the requested dataset, purpose and duration, and the owner's decision routes to a provisioning step or a denial notice. Confirm whether the approval record must be kept outside Dify, since the node stores responses inside the workflow run and your records policy decides where the authoritative copy lives.
Trigger-started runs need another path
Web app delivery of a Human Input form is not available in workflows started by a trigger. A webhook or schedule run that needs review must deliver the request by email, or the design must route it through a web app that a person starts. Check this constraint before committing a process design, because it changes who can respond and how quickly.
Oversight evidence is your decision
The node records responses within the workflow, including the button chosen, the form values and the response path. Whether those records are sufficient for an internal audit or external assessment is a judgment for your auditors and compliance owners, not something this node establishes. Ask them early which fields, timestamps and retention periods they expect, then test whether the run history shows them.
How to set up a Human Input approval in a self-hosted Dify
This sequence takes a self-hosted Dify workflow from version check to a tested approval gate, with a defined form, decision buttons, recipients, a timeout and a confirmed response record. The result is a workflow that pauses for a named person and resumes only on a recorded decision.
Confirm the Dify version and deployment
Record the Dify version your instance runs and confirm it is a release that includes the Human Input node in your environment. Check the Docker Compose stack against the self-hosting docs, including the core services, PostgreSQL, Redis and the mail-related settings you will need later. Read the upgrade guide for your target version on the Releases page before changing anything. Done when you can name the exact version, the deployment method and the node's availability in a test app on that instance.
Define form fields and decision buttons
Design the reviewer form before opening the canvas. List each field the reviewer must complete, such as a free-text rationale or a choice, because each field value becomes a workflow variable that downstream nodes read. Then define the decision buttons, giving each a title and a stable action ID, since the action ID and value are exposed downstream as __action_id and __action_value. Use action IDs that name the decision, such as approve or reject, so branches stay readable. Done when a written field list and button table exist and every branch condition refers to an action ID from that table.
Choose delivery channel and recipients
Select how the request reaches the reviewer. The Human Input node can deliver through the web app or by email, and the recipients can be specific workspace members, external email addresses or the whole workspace. Email recipients do not need a Dify account, which affects who can see and answer the request, so confirm that policy with your security owner. Note that web app delivery is not available in workflows started by a trigger, so choose email for trigger-started flows. Done when the channel and recipient list are written down and match your access rules.
Set the timeout strategy
Decide how long the workflow waits for a response and what happens if none arrives. The timeout strategy defines both the wait and the fallback path, so route the timeout branch to an explicit outcome such as escalation or closure rather than leaving it unhandled. Agree the wait period with the process owner and record it as a documented control, because the platform applies whatever you configure. Done when the timeout branch is wired to a named outcome and the owner has signed off the wait period and fallback in writing.
Configure outbound mail for email delivery
If you use email delivery, configure the mail settings in the environment file for your instance, then confirm the sending account, sender address and TLS requirements with your mail team. Keep credentials in your secrets store rather than in plain configuration files, and restrict outbound mail to the approved relay. Restart the affected services after changing the variables and check the variable reference for any new settings the version requires. Done when a test message sent from the instance arrives in an external mailbox and its sender identity matches policy.
Test with a non-production workflow
Build a copy of the workflow in a separate test app with the same Human Input node, a dummy approver and a low-impact downstream action. Run the approve path, the reject path and the timeout path, and confirm each routes to the intended branch. Test that a second reply to an email request is refused, since the request closes after the first response. Include a test of the web app path if reviewers will use it. Done when each path has a recorded test run and the downstream branch receives the expected action ID and form values.
Confirm what the response record contains
Inspect the run log for a completed test and list what it records: the reviewer's identity or address, the chosen action ID and value, the submitted field values, timestamps and the outcome of the timeout path if used. Compare that list with your review policy, then decide whether any extra evidence, such as an exported log or a retention rule, must be kept. Confirm retention settings for workflow logs with the team that owns them. Done when the record fields are matched against the policy in writing, and any gaps have an owner and a planned fix.
Trade-offs between web app and email review
The core decision is who the reviewer is and how Dify can prove they answered. Web app delivery of a Human Input form is available to workspace members, which means each reviewer needs a Dify account and a seat in the workspace before the workflow pauses. Email delivery reaches external addresses and does not require a Dify account, so it suits reviewers outside your organization or people who will never sign in. Before choosing, confirm how your identity provider and workspace membership work for the people who must approve, and whether web app delivery fits workflows that a trigger starts, since the Dify docs say web app delivery is not available in those workflows. Email also depends on mail infrastructure you run: confirm the outbound mail settings for your instance, who owns the sending domain, and how bounces and delivery failures will be detected, because a form that never arrives will stall the workflow until its timeout.
Both channels share two constraints that shape escalation. The request closes after the first response, so a second reviewer cannot act on the same form once one person has answered, and a forwarded email link does not create a second decision. Each Human Input node also has a timeout strategy that defines how long the workflow waits and what happens with no response. Design the escalation path explicitly: decide whether a timeout routes to a named backup approver with a new request, to a default decision that you can defend to an auditor, or to a stop that a human must restart. Test each branch with a deliberately unanswered request, because a timeout branch that nobody has exercised is often the first thing to fail during a real review.
The channel also changes the evidence you can show. A web app response is tied to an authenticated workspace identity, while an email response depends on who controls the inbox that received the link, so your record of the reviewer is weaker unless you add a verification step outside Dify. Whichever channel you choose, decide what evidence you will keep: the form values that become workflow variables, the __action_id and __action_value of the button pressed, the timestamp, and the workflow run log that links them. Confirm with your compliance owner and the auditor whether that combination is sufficient for the decision type, and whether your retention settings keep those run records for as long as the approval must be retrievable.
Security and operational considerations for human review
A human review step moves sensitive content out of the workflow and into email, forms and logs, so the controls around it matter as much as the node itself. The cards below cover who receives forms, how secrets and outbound requests are protected, where form content can leak, and how upgrades change the settings you rely on.
Who may receive external forms
Email delivery can reach external addresses outside your workspace, and recipients do not need a Dify account. Decide in advance which roles may be named as reviewers, whether external reviewers are allowed at all, and what each reviewer can see in the form body. Because the request closes after the first response, a forwarded email can let an unintended person make the decision. Confirm your mail routing and who controls the distribution list before go-live.
Protecting SECRET_KEY and mail credentials
SECRET_KEY signs session cookies and JWTs and encrypts OAuth credentials, and changing it after deployment logs out all users. Store it in your secrets manager, generate it once, and document who can read it. Outbound mail credentials used to deliver review requests should follow the same rule: keep them out of .env files committed to source control and rotate them through a planned change. Confirm how your operators back up .env without copying plain-text secrets into backup archives.
Outbound request filtering with SSRF_PROXY
Review workflows call out to mail services and other endpoints, so outbound traffic needs a controlled path. The SSRF_PROXY settings route outbound requests through a proxy that blocks internal and private IP ranges, which limits what a workflow can reach from inside your network. Test that the mail relay you need is reachable through the proxy path and that no internal address is accidentally allowed. Confirm the proxy configuration in your own network before you rely on it for approvals.
Keeping form content out of logs
Form field values become workflow variables, so the answers a reviewer types can appear wherever workflow data is recorded. Decide which log stores, traces and error reports receive that data, and who can read them. Set retention on workflow logs to match your privacy policy, and check whether any external observability tool receives full payloads. Confirm the logging behavior of your deployed version in a test workflow before approvals carry real customer or patient data.
Checking .env.example after upgrades
Upgrades can add or change environment variables, and a human review step depends on the settings that control delivery and access. After every version change, compare your .env with .env.example for the target version, and read the release notes for security changes that affect the Human Input node, the sandbox or service authentication. Back up before each upgrade, then rerun a test approval flow. Confirm the upgrade guide for each target release on the releases page.
Recording who decided and when
A review process that needs recorded oversight must show which reviewer chose which action button and when. The node exposes the chosen decision as __action_id and __action_value, and form values become workflow variables, so the workflow itself can write the decision to your system of record. Decide where the audit trail lives, how long it is kept, and how you handle timeouts that expire without a response. Confirm with your compliance team which evidence they need before designing the write-back step.
Limits to confirm before you design a review step
Can a Human Input form be delivered through the web app for trigger-started workflows?
No. The Dify docs say web app delivery of a Human Input form is not available in workflows started by a trigger. If a review step must be triggered by an event such as a webhook, plan for email delivery or a different review channel, and confirm this limit against the Dify version you run. Test the full path end to end before you commit to the design, since a trigger-started workflow that stalls at a review step with no reachable form is a common failure to catch early.
What happens when more than one person responds to a review request?
The request closes after the first response. Dify treats the first submitted answer as the decision, so the workflow continues on that response and later replies do not change the outcome. Design your approval rules around this: if two reviewers must both sign off, a single Human Input node cannot enforce that by itself, and you need to model the second approval as a separate step or a separate process. Write this rule into your review procedure so reviewers understand that the first click counts.
How does timeout behavior work, and how do I verify it?
A timeout strategy defines how long the workflow waits for a response and what happens when no one answers. The exact behavior, including available options and what the workflow does afterward, can change between releases, so do not rely on memory or a blog post. Confirm the options in the Human Input documentation for your version, then run a test in a staging workspace with a short timeout and record which branch the workflow takes. Keep that test result as evidence for your design file.
Do external reviewers need a Dify account to respond?
No. Email recipients can respond without a Dify account, because the form is delivered by email to external addresses. This makes email the practical channel for reviewers outside your workspace, such as a客户 contact or an outside legal adviser. It also means the email path must work reliably, so confirm that your SMTP settings, sender domain and spam controls allow review emails to reach external mailboxes before any reviewer depends on them.
What must work in the mail setup before external approvals are reliable?
Outbound email must be configured and tested from the Dify environment, including the sending account, authentication, TLS and the sender address that recipients see. Check the environment variable reference for the mail settings in your version, then send a test request to an external mailbox that you control. Verify that links in the email reach the correct form, that the form loads over your public address, and that replies are recorded against the right workflow run. Involve your email or security team early, because outbound mail policy is usually owned outside the Dify team.
Will the review step behave the same after I upgrade Dify?
Not guaranteed, so treat each upgrade as a check. Dify publishes minor releases roughly monthly, and node behavior, form options and timeout handling can change between them. Read the release notes and the Human Input documentation for the target version before upgrading, back up your instance first as the Docker Compose upgrade guidance advises, and rerun your review tests in staging. Record the version in your approval procedure so an auditor can see which behavior governed a given decision.
Is a Human Input node enough to meet a recorded human oversight requirement?
It records a human decision inside the workflow, but it does not by itself prove that a regulation or internal policy is satisfied. Oversight evidence usually also needs defined reviewer roles, criteria for what the reviewer checks, retention of the decision and its context, and a process for handling timeouts. Confirm with your compliance lead and any independent assessor which evidence they expect, then decide which parts Dify records and which parts your process must supply. DeployOpen prepares systems and evidence for compliance assessments but does not issue audit reports or certifications.
How DeployOpen works on this
DeployOpen plans, builds, documents and supports self-hosted Dify inside your own infrastructure, including the Human Input node that pauses workflows for a person. Engagements are fixed-scope, so the approval points, reviewers, delivery channels and timeouts are agreed in writing before any workflow is changed.
How we scope
- Map each workflow step that needs a person to a named review decision and its consequence.
- Agree who may respond, through the web app, email to external addresses, or workspace members.
- Define decision buttons, form fields and the timeout strategy for every Human Input node in writing.
How we build
- Configure Human Input nodes with clear button titles and action IDs that route downstream branches.
- Map form fields to workflow variables so reviewer input is stored and passed on consistently.
- Test pause, resume, timeout and rejection paths, including workflows started by triggers that cannot use web app delivery.
How we hand over
- Document each review point, its approvers, timeout behavior and the evidence it records.
- Walk operators through reviewing pending requests and handling expired or unanswered ones.
- Provide exported DSL files and a configuration record so changes stay under your version control.
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer after handover.
- Re-test review paths when Dify versions change how nodes, forms or triggers behave.
- Review approval routing whenever reviewers, teams or regulatory expectations change.
