event (v1)

event (v1)

Handle Lark event subscriptions and webhook callbacks for real-time updates

Category: development Source: larksuite/cli

event (v1): Real-Time Event Handling for Lark on Happycapy Skills

The event (v1) skill (lark-event) for the Happycapy Skills platform provides a robust solution for developers who need to handle Lark (Feishu) event subscriptions and webhook callbacks with real-time responsiveness. By leveraging WebSocket long connections, this skill enables the efficient streaming of various Lark events directly to your automation pipelines or development workflows. This article covers what the skill is, its benefits, usage patterns, common scenarios, and essential caveats for getting the most from lark-event.

What Is This Skill?

The event (v1) skill enables developers to subscribe to Lark events via WebSocket, capturing changes in messages, contacts, calendars, and more. Events are streamed as NDJSON (newline-delimited JSON) to stdout, making the output easy to consume for further processing or integration with other tools. The skill is designed for real-time event-driven architectures, allowing for:

  • Low-latency event monitoring directly from Lark
  • Advanced routing with regular expressions
  • Agent-friendly compact output mode
  • Optional file output for persistence or offline processing

This skill requires the lark-cli binary and operates mainly through the command line, with shortcuts that abstract away complex commands for common tasks.

Why Use the event (v1) Skill?

Developers and system integrators often need to build applications or automations that react instantly to changes within Lark. The standard webhook model, while useful, can introduce latency and complexity in managing HTTP endpoints. lark-event addresses these challenges with:

  • Real-Time Updates: WebSocket-based streaming ensures your application receives events as soon as they occur, with minimal overhead.
  • Flexible Output: The NDJSON format is ideal for streaming data and easy integration with Unix pipelines, log processors, or event-driven systems.
  • Advanced Filtering: Built-in support for regex-based routing allows you to process only the events you care about, reducing noise and improving efficiency.
  • Developer Ergonomics: The skill provides a simplified CLI interface and high-level shortcuts so you can get started quickly without deep knowledge of the Lark API.
  • Agent Compatibility: A compact output format makes it easier to integrate with other automated agents and data consumers.

How to Use the event (v1) Skill

Prerequisites

  • Install lark-cli: Ensure the Lark CLI tool is available in your environment.
  • Authentication and Permissions: Before subscribing to events, review and configure the necessary authentication and permissions as detailed in the lark-shared documentation.

Basic Usage

The recommended way to use this skill is through its Shortcut command, which abstracts away the complexity of direct CLI invocation. The main shortcut provided is +subscribe.

Subscribe to Lark Events

To start listening to Lark events:

lark-cli event +subscribe

This command establishes a WebSocket connection to Lark and streams all subscribed events to stdout in NDJSON format.

Example NDJSON Output
{"event":"message.receive","data":{"message_id":"om_12345","content":"Hello"}}
{"event":"user.added","data":{"user_id":"ou_67890"}}
Advanced Usage
  • Compact Output: For agent-friendly output, use the --compact flag.
  • Regex Routing: Filter events using the --route flag.
  • File Output: Save events to a file for later processing.
lark-cli event +subscribe --compact --route="message.*" --output=events.log

This command listens only for message-related events, outputs them in compact form, and writes the results to events.log.

CLI Help

For a full list of options, run:

lark-cli event --help

When to Use the event (v1) Skill

Consider integrating lark-event in the following scenarios:

  • Real-Time Notification Systems: When you need to trigger actions or alerts instantly upon changes in Lark (such as new messages, calendar updates, or contact modifications).
  • Event-Driven Pipelines: As the first step in a larger automation, where subsequent stages depend on specific events from Lark.
  • Audit Logging and Compliance: When maintaining a real-time, reliable audit trail of activity in your Lark workspace.
  • Bot Development: For bots that must respond to user actions or system events with minimal latency.

Important Notes

  • Authentication Required: Ensure your environment is properly authenticated and has the necessary permissions to receive the desired events. Refer to the shared skill documentation for setup details.
  • Bot-Only: Event subscription via WebSocket is available only to bots, not individual users.
  • NDJSON Output: The default output is NDJSON, which is optimized for streaming and further processing but may require parsing before use in certain applications.
  • Event Filtering: Leverage regex routing to avoid processing unnecessary events and reduce resource consumption.
  • Security: Always follow best practices for securing your event pipelines, especially when writing outputs to files or integrating with external systems.
  • Extensibility: The skill is designed to fit into larger event-driven architectures on Happycapy Skills, and its output is suitable for chaining with other skills or tools.

The event (v1) skill provides a powerful, real-time interface for Lark event handling, making it a key tool for developers building reactive and event-driven applications on the Happycapy Skills platform. By following the usage patterns and notes outlined above, you can integrate Lark events into your workflows efficiently and securely.