Practical Tutorial on the Feishu Error Alert Strategy: Pushing Integration Platform Exceptions to Group Chats in Real Time

What This Strategy Solves

In a sales-order integration chain with six parallel sync strategies, any single failure—an expired token on the target side, a missing field mapping, or a throttling block—must surface to the on-call engineer quickly. The traditional approach is to log into the integration platform and read the "strategy error detail" page manually, which essentially pushes the responsibility for noticing problems onto the habit of "remembering to check."

The Feishu Error Alert strategy does one thing: it lets the integration platform speak up by itself. The source side polls the error-detail API every few minutes, filters records with status "error," assembles a structured message, and drops it onto a Feishu bot webhook. On-call engineers see, right inside their group chat, which strategy, which record, at what time, hit what kind of problem. It does not move business data; it moves the platform's own health status. It is a typical "meta-integration" strategy in the chain.

Data Flow and Field Mapping

The whole pipeline is "Platform → Platform internal error table → Feishu bot." No business system is involved. The key fields are mapped as follows:

Note that strategy_name on the source side is an identifier at the "number" granularity (the interface paging key), while on the target side it becomes display text. The two share a name but carry different semantics, so do not blindly copy field values when writing mapping scripts.

How to Configure on Qeasy

On the Qeasy data integration platform, this strategy consists of two WebAPI steps, chained by the strategy-ID list.

The source step is StrategyErrorDetail, a query-type WebAPI. Its request body is made of recentSeconds, ids, and status. Hard-code the strategy IDs you want to monitor into ids, comma-separated; set status to 3 by default, which means errors only. If you also want to watch "duplicate" or "queued," change it to 3,1,5, but be aware that alert noise rises sharply, which is not recommended in the first phase.

The target step is a Feishu custom bot incoming webhook at path /bot/v2/hook, method POST. Four common patterns we have reused on customer sites:

1. Centralized code mapping: do not scatter webhook_id across strategies; instead, keep it in a platform-level parameter configuration so that switching or creating a group touches only one place.
2. Header and body in phases: implement the alert header (strategy name + time) first, then add the body (links to error detail) later. Avoid shipping an over-complex template all at once.
3. Dual-track of incremental and full sync: use recentSeconds on the source side for incremental polling; add a separate full-recheck strategy running overnight as a safety net.
4. Placeholder naming convention: keep {{strategy_name}}, {{number}}, {{response_at\|datetime}} exactly as in the material; renaming on the fly will break script parsing.

Implementation Steps

We split rollout into three phases.

Phase 1: incremental starting point. Configure only the source StrategyErrorDetail query first. Set recentSeconds to 60, list a single strategy ID, fix status to 3. Run the strategy once manually in Qeasy and confirm that the response contains strategy_name, strategy_id, number, and response_at. Patch the mapping if any field is missing.

Phase 2: full trigger. Wire up the target webhook and validate the message body with a test bot inside the group. Validate two points: whether {{response_at\|datetime}} is formatted correctly, and whether an over-long problem field is truncated. Feishu cards have a length cap on long text, so either truncate or replace with a markdown link that jumps to the strategy detail page.

Phase 3: scheduling frequency. The source strategy runs on 1-59/8 * * * *, which is every 8 minutes, offset from the full minute to avoid pile-ups. The target strategy runs on 3-59/8 8-23 * * *, starting at minute 3 within working hours. Both crons deliberately avoid the top of the hour, and the target runs two minutes after the source so that errors have already landed. This "off-peak and off-minute" pattern is a small detail verified across many customer sites.

Pitfall Retrospective

1. A typical mistake is passing only status 3. During a first launch a customer monitored only errors and missed a night-long "queued" pile-up. The safer approach is to set status to 3,5 first, observe alert volume for a week, then narrow down.
2. Strategy IDs missing or wrong. If ids is empty or mistyped, the call returns stale errors from unrelated strategies. A common practice is to keep all monitored IDs as one constant and append whenever a new strategy is added.
3. Webhook throttled. Feishu custom bots enforce a rate limit per webhook, so an alert storm can be throttled. The safer approach is to deduplicate so that the same strategy and the same number within five minutes fire only once.
4. Forgetting \|datetime on the time placeholder. {{response_at}} outputs a raw ISO timestamp; only with \|datetime does it become YYYY-MM-DD HH:mm:ss.
5. Mixed-tenant alerts. In a shared multi-tenant platform, lessee_name must be carried; otherwise, errors from different customers land in the same group and cross-contaminate triage.

Applicable and Non-Applicable Scenarios

Applicable: multi-strategy parallelism, 24×7 monitoring, on-call engineers collaborating on Feishu, and small-to-mid integration chains that need "exception equals message." Not applicable: extremely high daily error volume (tens of thousands or more)—that should go to a dedicated log alerting platform; nor for offline batch pipelines tolerant of high latency, where manual inspection is more cost-effective.