Feishu Approval Trigger Plugin

Receive Feishu (Lark) approval event notifications and trigger Dify workflows. Supports encrypted transmission, signature verification, and multiple event format versions.

Why use this plugin

• Real-time triggers: Start Dify workflows immediately after approval without polling
• Secure & reliable: Supports Feishu's recommended dual security mechanism (signature verification + AES-256 encryption)
• Auto-filtering: Only processes APPROVED status approvals, automatically ignoring other statuses
• Out-of-the-box: Compatible with Feishu v1.0 and v2.0 event formats without additional configuration

What is Feishu Approval?

• Feishu Approval is an approval process management system provided by Feishu Open Platform
• Through event subscription, you can receive real-time approval status change notifications
• Official documentation: https://open.feishu.cn/document/server-docs/approval-v4/event/function-introduction

Features

✅ Dual Security Modes

Mode	Configuration	Security Features	Recommended Use Case
Encrypted Mode	Encrypt Key	Signature verification + AES-256-CBC encryption	Production (Recommended)
Plaintext Mode	Verification Token only	Basic Token verification	Development/Testing

✅ Event Format Compatibility

• v1.0 Format: Feishu approval events (approval_task)
• v2.0 Format: General event subscription (approval.instance.status_updated)
• Automatic detection and adaptation, no manual configuration required

✅ Intelligent Event Filtering

• Only triggers workflows for status == "APPROVED" approvals
• Other statuses (PENDING, REJECTED, etc.) are automatically ignored
• Avoids unnecessary workflow executions

✅ Output Variables

The plugin provides the following variables to Dify workflows:

Variable Name	Type	Description	Example
instance_code	string	Approval instance Code	B5463FE5-14CF-49D9-9C7E-5E7B7BEACCBF
approval_code	string	Approval definition Code	9540C9E3-48B6-4812-A2F3-3E011190BDB4
status	string	Approval status (always APPROVED)	APPROVED
operate_time	string	Status change timestamp	1762376996307
app_id	string	Feishu App ID	cli_a9837cdad77f500c
event_id	string	Unique event ID (for idempotency)	dec15e6d19502ff7c8cfcfa3f3e67842
uuid	string	Approval instance UUID	eac5a638542c9f69a70f210748d435a7

Setup Guide

Step 1: Create Application in Feishu Developer Console

1. Visit Feishu Developer Console
2. Create an "Enterprise Self-Built Application"
3. Enter application management page

Step 2: Enable Bot Feature (Optional but Recommended)

1. Navigate to Features → Add Application Features
2. Enable Bot feature

Step 3: Configure Permissions

1. Navigate to Permission Management
2. Add the following permissions:
   • approval:approval - View and comment on approvals
   • approval:approval:readonly - Get approval information (recommended)

Step 4: Obtain Credentials and Keys

4.1 Get App ID and App Secret

1. Navigate to Credentials & Basic Information
2. Copy App ID (format: cli_xxx...)
3. Copy App Secret

4.2 Get Verification Token

1. Navigate to Events & Callbacks
2. Ensure Event Subscription toggle is enabled
3. Find Verification Token in the Security Policy section
4. Copy the Token (format: x7T88t...)

4.3 Configure Encrypt Key (Strongly Recommended)

1. In the same Security Policy section
2. Find Encrypt Key
3. If empty, click the Generate button
4. Immediately copy and save the key (old key becomes invalid after reset)

Step 5: Configure Subscription in Dify

1. Install/import this plugin in Dify
2. Fill in the following information when creating a subscription:

Configuration	Required	Description	Location
App ID	✅ Required	Feishu App ID	Credentials & Basic Information
App Secret	✅ Required	Feishu App Secret	Credentials & Basic Information
Verification Token	✅ Required	Event verification token	Events & Callbacks → Security Policy
Encrypt Key	🟡 Recommended	Event encryption key	Events & Callbacks → Security Policy

3. Copy the Webhook URL generated by Dify

Step 6: Configure Event Subscription in Feishu

1. In Feishu Developer Console, navigate to Events & Callbacks
2. Paste Dify's Webhook URL in the Request URL field
3. Click Save (Feishu will send a URL verification request)
4. If configured correctly, verification success will be displayed

Step 7: Subscribe to Approval Events

1. In the Event Configuration section on the same page
2. Click Add Event
3. Search and add:
   • approval.instance.status_updated (v2.0)
   • or approval_task (v1.0)
4. Save configuration

Step 8: Publish Application Version

⚠️ Critical Step: Feishu configuration only takes effect after the application is published!

1. Navigate to Version Management & Publishing
2. Create new version
3. Submit and publish

Usage

Using in Dify Workflow

1. Create a new Workflow
2. Select Plugin Trigger as trigger node type
3. Select plugin: Feishu Approval Trigger
4. Select event: Feishu Approval (Approved)
5. Workflow will automatically trigger when Feishu approval is approved

Using Output Variables

In subsequent workflow nodes, you can reference the following variables:

# Example: Use in LLM node
Approval Instance Code: {{instance_code}}
Approval Definition Code: {{approval_code}}
Approval Status: {{status}}
Operation Time: {{operate_time}}

Typical Use Cases

1. Auto Notification: Automatically send notifications to WeChat Work, DingTalk, etc. after approval
2. Data Sync: Synchronize approval data to database or CRM system
3. Process Chaining: Trigger downstream approvals or business processes
4. Intelligent Processing: Use LLM to analyze approval content and automatically execute subsequent operations

Security Mode Details

🔒 Encrypted Mode (Strongly Recommended)

Activation Condition: Configure Encrypt Key

Security Features:

1. Signature Verification (Level 1)

   • Algorithm: SHA256(timestamp + nonce + encrypt_key + raw_body)
   • Verifies HTTP Headers: X-Lark-Signature
   • Prevents request tampering

2. Payload Encryption (Level 2)

   • Algorithm: AES-256-CBC
   • Key Derivation: SHA256(encrypt_key)
   • Prevents data eavesdropping

3. Token Verification (Level 3)

   • Verifies token field in event
   • Dual authentication

Configuration Requirements:

✅ Configure Encrypt Key in Feishu Console
✅ Fill in Encrypt Key in Dify subscription

🔓 Plaintext Mode (Testing Only)

Activation Condition: Do not configure Encrypt Key

Security Features:

• ⚠️ Token verification only (plaintext transmission)
• ⚠️ Cannot prevent man-in-the-middle attacks
• ⚠️ Cannot prevent data eavesdropping

Applicable Scenarios:

• Local development testing
• Internal network environment
• Non-sensitive data

URL Verification (Challenge) Handling

The plugin automatically handles Feishu's URL verification requests:

1. Plaintext Challenge (Encrypt Key not configured)

   Feishu sends: {"type": "url_verification", "challenge": "xxx"}
   Plugin responds: {"challenge": "xxx"}

2. Encrypted Challenge (Encrypt Key configured)

   Feishu sends: {"encrypt": "base64_encrypted_string"}
   Plugin auto: Decrypt → Extract challenge → Respond

Response Time: < 1 second (meets Feishu requirements)

Troubleshooting

❌ Token Verification Failed

Error Message: TriggerValidationError: Invalid Verification Token

Solutions:

1. Check if Verification Token configured in Dify matches Feishu console
2. Ensure no extra spaces or line breaks
3. If Encrypt Key was modified, Verification Token may have changed, need to recopy

❌ Signature Verification Failed

Error Message: TriggerValidationError: Invalid signature

Solutions:

1. Check if Encrypt Key configured in Dify is correct
2. Ensure Feishu console's Encrypt Key matches Dify
3. If key was reset, need to update subscription configuration in Dify

❌ Decryption Failed

Error Message: TriggerDispatchError: Failed to decrypt payload

Solutions:

1. Check if Encrypt Key is correct
2. Try removing Encrypt Key and test with plaintext mode
3. Ensure Encrypt Key is properly configured in Feishu console

❌ Event Not Triggered

Possible Causes:

1. Approval status is not APPROVED

   • Plugin only processes APPROVED status
   • Other statuses (PENDING, REJECTED) are silently ignored

2. Incorrect event subscription

   • Ensure approval events are subscribed in Feishu console
   • Check if application version is published

3. Insufficient permissions

   • Check if application has approval-related permissions
   • Ensure application is published and effective

❌ URL Verification Failed

Error Message: Verification fails when saving Webhook URL in Feishu

Solutions:

1. Ensure plugin is running
2. Check if Dify Webhook URL is accessible
3. If using Encrypt Key, ensure configuration is correct
4. Check plugin logs to see if verification request was received

Technical Details

Supported Event Formats

v1.0 Format (Feishu Approval Events)

{
  "uuid": "...",
  "token": "x7T88tRQv3...",
  "type": "event_callback",
  "ts": "1762376996.467246",
  "event": {
    "type": "approval_task",
    "status": "APPROVED",
    "instance_code": "B5463FE5-14CF-49D9-9C7E-5E7B7BEACCBF",
    "approval_code": "9540C9E3-48B6-4812-A2F3-3E011190BDB4",
    "operate_time": "1762376996307",
    "app_id": "cli_a9837cdad77f500c",
    ...
  }
}

v2.0 Format (General Event Subscription)

{
  "schema": "2.0",
  "header": {
    "event_id": "...",
    "event_type": "approval.instance.status_updated",
    "token": "x7T88tRQv3...",
    "app_id": "cli_a9837cdad77f500c"
  },
  "event": {
    "object": {
      "status": "APPROVED",
      "instance_code": "...",
      "approval_code": "...",
      ...
    }
  }
}

Data Flow Architecture

Feishu Approval System
    ↓ (Approval passed)
Feishu Event Subscription
    ↓ (HTTP POST)
Dify Webhook URL
    ↓
1. Signature Verification (if Encrypt Key configured)
2. Payload Decryption (if encrypted)
3. Token Verification
4. Event Type Identification (v1.0/v2.0)
    ↓
5. Status Filtering (APPROVED only)
    ↓
6. Data Transformation → Variables
    ↓
Trigger Dify Workflow

Performance Requirements

• Response Time: < 3 seconds (Feishu requirement)
• Challenge Response: < 1 second (Feishu requirement)
• Idempotency: Use event_id or uuid for deduplication

Best Practices

✅ Production Environment Checklist

• Configure Encrypt Key (required)
• Verify signature verification works correctly
• Test that approved approvals correctly trigger workflows
• Test that other statuses (REJECTED) do not trigger workflows
• Implement idempotency check in Dify workflow (using event_id variable)
• Configure alert monitoring (if webhook fails)

✅ Security Recommendations

1. Must use Encrypt Key (production environment)

   • Prevent data leakage (approval content may contain sensitive information)
   • Prevent request forgery attacks

2. Regularly rotate keys

   • Regularly update App Secret and Encrypt Key
   • Update Dify subscription configuration after rotation

3. Principle of least privilege

   • Only grant necessary approval-related permissions
   • Avoid granting excessive API permissions

✅ Idempotency Implementation

Feishu uses an "at-least-once delivery" strategy, where the same event may be pushed multiple times.

✅ Monitoring Recommendations

• Monitor Webhook failure rate
• Set alerts: consecutive failures > 3 times
• Regularly check Feishu application subscription status

Related Links

• Feishu Open Platform
• Feishu Approval API Documentation
• Feishu Event Subscription Guide
• Dify Trigger Plugin Documentation

---

Maintainer: stream Version: 0.0.1 Last Updated: 2025-01-06