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

• Visit Feishu Developer Console
• Create an "Enterprise Self-Built Application"
• Enter application management page

Step 2: Enable Bot Feature (Optional but Recommended)

• Navigate to Features → Add Application Features
• Enable Bot feature

Step 3: Configure Permissions

• Navigate to Permission Management
• 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

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

4.2 Get Verification Token

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

4.3 Configure Encrypt Key (Strongly Recommended)

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

Step 5: Configure Subscription in Dify

• Install/import this plugin in Dify
• 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

• Copy the Webhook URL generated by Dify

Step 6: Configure Event Subscription in Feishu

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

Step 7: Subscribe to Approval Events

• In the Event Configuration section on the same page
• Click Add Event
• Search and add:

• approval.instance.status_updated (v2.0)

• or approval_task (v1.0)
• Save configuration

Step 8: Publish Application Version

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

• Navigate to Version Management & Publishing
• Create new version
• Submit and publish

Usage

Using in Dify Workflow

• Create a new Workflow
• Select Plugin Trigger as trigger node type
• Select plugin: Feishu Approval Trigger
• Select event: Feishu Approval (Approved)
• 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

• Auto Notification: Automatically send notifications to WeChat Work, DingTalk, etc. after approval
• Data Sync: Synchronize approval data to database or CRM system
• Process Chaining: Trigger downstream approvals or business processes
• 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:

• Signature Verification (Level 1)

• Algorithm: SHA256(timestamp + nonce + encrypt_key + raw_body)

• Verifies HTTP Headers: X-Lark-Signature

• Prevents request tampering

• Payload Encryption (Level 2)

• Algorithm: AES-256-CBC

• Key Derivation: SHA256(encrypt_key)

• Prevents data eavesdropping

• 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:

• Plaintext Challenge (Encrypt Key not configured)

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

• 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:

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

❌ Signature Verification Failed

Error Message: TriggerValidationError: Invalid signature

Solutions:

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

❌ Decryption Failed

Error Message: TriggerDispatchError: Failed to decrypt payload

Solutions:

• Check if Encrypt Key is correct
• Try removing Encrypt Key and test with plaintext mode
• Ensure Encrypt Key is properly configured in Feishu console

❌ Event Not Triggered

Possible Causes:

• Approval status is not APPROVED

• Plugin only processes APPROVED status

• Other statuses (PENDING, REJECTED) are silently ignored

• Incorrect event subscription

• Ensure approval events are subscribed in Feishu console

• Check if application version is published

• 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:

• Ensure plugin is running
• Check if Dify Webhook URL is accessible
• If using Encrypt Key, ensure configuration is correct
• 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

• Must use Encrypt Key (production environment)

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

• Prevent request forgery attacks

• Regularly rotate keys

• Regularly update App Secret and Encrypt Key

• Update Dify subscription configuration after rotation

• 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