Flow HITL Management

​

Overview

​

Key Benefits

• Simple mental model: Email addresses are universal; no need to manage platform users or roles
• External responders: Anyone with an email can respond, even non-platform users
• Dynamic assignment: Pull assignee email directly from flow state (e.g., sales_rep_email)
• Reduced configuration: Fewer settings to configure, faster time to value
• Email as primary channel: Most users prefer responding via email over logging into a dashboard

​

Setting Up Human Review Points in Flows

from crewai.flow.flow import Flow, start, listen
from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult

class ContentApprovalFlow(Flow):
    @start()
    def generate_content(self):
        # AI generates content
        return "Generated marketing copy for Q1 campaign..."

    @listen(generate_content)
    @human_feedback(
        message="Please review this content for brand compliance:",
        emit=["approved", "rejected", "needs_revision"],
    )
    def review_content(self, content):
        return content

    @listen("approved")
    def publish_content(self, result: HumanFeedbackResult):
        print(f"Publishing approved content. Reviewer notes: {result.feedback}")

    @listen("rejected")
    def archive_content(self, result: HumanFeedbackResult):
        print(f"Content rejected. Reason: {result.feedback}")

    @listen("needs_revision")
    def revise_content(self, result: HumanFeedbackResult):
        print(f"Revision requested: {result.feedback}")

​

Decorator Parameters

​

Platform Configuration

​

Email Notifications

​

SLA Target

​

Email Notifications & Responses

​

How Email Responses Work

​

Response Format

• Emit option: If the reply matches an emit option (e.g., “approved”), it’s used directly
• Free-form text: Any text response is passed to the flow as feedback
• Plain text: The first line of the reply body is used as feedback

​

Confirmation Emails

​

Email Token Security

• Tokens are cryptographically signed for security
• Tokens expire after 7 days
• Sender email must match the token’s authorized email
• Confirmation/error emails are sent after processing

​

Routing Rules

​

Rule Structure

{
  "name": "Approvals to Finance",
  "match": {
    "method_name": "approve_*"
  },
  "assign_to_email": "[email protected]",
  "assign_from_input": "manager_email"
}

​

Matching Patterns

​

Assignment Priority

1. Dynamic assignment (assign_from_input): If configured, pulls email from flow state
2. Static email (assign_to_email): Falls back to configured email
3. Deployment creator: If no rule matches, the deployment creator’s email is used

​

Dynamic Assignment Example

{
  "name": "Route to Sales Rep",
  "match": {
    "method_name": "review_*"
  },
  "assign_from_input": "sales_rep_email"
}

​

Auto-Response

​

Configuration

​

Use Cases

• SLA compliance: Ensure flows don’t hang indefinitely
• Default approval: Auto-approve low-risk requests after timeout
• Graceful degradation: Continue with a safe default when reviewers are unavailable

​

Review Process

​

Dashboard Interface

• Markdown Rendering: Rich formatting for review content with syntax highlighting
• Context Panel: View flow state, execution history, and related information
• Feedback Input: Provide detailed feedback and comments with your decision
• Quick Actions: One-click emit option buttons with optional comments

​

Response Methods

​

History & Audit Trail

• Decision history (approve/reject/revise)
• Reviewer identity and timestamp
• Feedback and comments provided
• Response method (email/dashboard/API)
• Response time metrics

​

Analytics & Monitoring

​

Performance Dashboard

​

Audit & Compliance

• Complete decision history with timestamps
• Reviewer identity verification
• Immutable audit logs
• Export capabilities for compliance reporting

​

Common Use Cases

​

Webhooks API

• Building custom approval UIs
• Integrating with internal tools (Jira, ServiceNow, custom dashboards)
• Routing approvals to third-party systems
• Mobile app notifications
• Automated decision systems

​

Configuring Webhooks

​

Webhook Events

​

Webhook Payload

{
  "event": "new_request",
  "request": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "flow_id": "flow_abc123",
    "method_name": "review_article",
    "message": "Please review this article for publication.",
    "emit_options": ["approved", "rejected", "request_changes"],
    "state": {
      "article_id": 12345,
      "author": "[email protected]",
      "category": "technology"
    },
    "metadata": {},
    "created_at": "2026-01-14T12:00:00Z"
  },
  "deployment": {
    "id": 456,
    "name": "Content Review Flow",
    "organization_id": 789
  },
  "callback_url": "https://api.crewai.com/...",
  "assigned_to_email": "[email protected]"
}

​

Responding to Requests

POST {callback_url}
Content-Type: application/json

{
  "feedback": "Approved. Great article!",
  "source": "my_custom_app"
}

​

Security

​

Webhook Security

• HMAC-SHA256 signatures: Every webhook includes a cryptographic signature
• Per-webhook secrets: Each webhook has its own unique signing secret
• Encrypted at rest: Signing secrets are encrypted in our database
• Timestamp verification: Prevents replay attacks

​

Signature Headers

​

Verification

import hmac
import hashlib

expected = hmac.new(
    signing_secret.encode(),
    f"{timestamp}.{payload}".encode(),
    hashlib.sha256
).hexdigest()

if hmac.compare_digest(expected, signature):
    # Valid signature

​

Error Handling

​

Security & RBAC

​

Dashboard Access

​

Email Response Authorization

1. The reply-to token encodes the authorized email
2. Sender email must match the token’s email
3. Token must not be expired (7-day default)
4. Request must still be pending

​

Audit Trail

• Request creation
• Assignment changes
• Response submission (with source: dashboard/email/API)
• Flow resume status

​

Troubleshooting

​

Emails Not Sending

1. Check “Email Notifications” is enabled in configuration
2. Verify routing rules match the method name
3. Verify assignee email is valid
4. Check deployment creator fallback if no routing rules match

​

Email Replies Not Processing

1. Check token hasn’t expired (7-day default)
2. Verify sender email matches assigned email
3. Ensure request is still pending (not already responded)

​

Flow Not Resuming

1. Check request status in dashboard
2. Verify callback URL is accessible
3. Ensure deployment is still running

​

Best Practices

1. Use Dynamic Assignment: Pull assignee emails from your flow state for flexible routing.
2. Configure Auto-Response: Set up a fallback for non-critical reviews to prevent flows from hanging.
3. Monitor Response Times: Use analytics to identify bottlenecks and optimize your review process.
4. Keep Review Messages Clear: Write clear, actionable messages in the @human_feedback decorator.
5. Test Email Flow: Send test requests to verify email delivery before going to production.

​

Related Resources