DEV Community

Ivan Kabar
Ivan Kabar

Posted on

Adding Low-Noise Error Alerts to an Express API with Wotchi

#opensource #node #express #tutorial

When an Express service starts failing, the first signal is often a noisy terminal, a long log stream, or a customer report.

I built Wotchi as a small, in-process alerting layer for Node.js services. It removes sensitive values, groups repeated failures, and sends bounded alerts to a destination you already use—without requiring a hosted dashboard or a new observability account.

In this tutorial, we will add Wotchi to a small Express API and send a useful alert when a route fails.

Wotchi is currently a public beta (0.1.0-beta.6), so its API may change before the first stable release.

What we are building

The request path will look like this:

Express route
  -> Wotchi error middleware
  -> normalize and redact
  -> group and apply cooldown
  -> bounded notification queue
  -> console, Telegram, or HTTPS webhook
Enter fullscreen mode Exit fullscreen mode

Wotchi observes the error, but your application keeps ownership of the HTTP response.

Install

Create an Express application and install Wotchi:

npm install express @futurewindai/wotchi@beta
Enter fullscreen mode Exit fullscreen mode

Wotchi supports Node.js >=18.18.0, ESM, CommonJS, and TypeScript types. The Express integration supports Express 4 and 5.

Add Wotchi to Express

Here is a complete small example:

import express from "express";
import {
  consoleNotifier,
  createWotchi,
} from "@futurewindai/wotchi";
import { wotchiErrorHandler } from "@futurewindai/wotchi/express";

const app = express();

const wotchi = createWotchi({
  service: "orders-api",
  environment: "development",
  // Use 1 here so the alert appears immediately while testing.
  grouping: {
    alertThreshold: 1,
  },
  notifiers: [consoleNotifier()],
});

app.get("/orders/:id", (_request, _response, next) => {
  next(new Error("Database query failed"));
});

// Register Wotchi after your routes.
app.use(wotchiErrorHandler(wotchi));

// Keep your existing final error handler after Wotchi.
app.use((error, _request, response, _next) => {
  console.error(error);

  response.status(500).json({
    error: "Internal server error",
  });
});

app.listen(3000, () => {
  console.log("Orders API listening on port 3000");
});
Enter fullscreen mode Exit fullscreen mode

The important detail is middleware order: Wotchi belongs after the routes and before the final error handler.

Requesting /orders/123 now produces the normal HTTP response and a console alert similar to this:

Wotchi — Medium incident
Service: orders-api
Environment: development
Summary: Observed 1 occurrences of Error: Database query failed.
Occurrences: 1
First seen: 2026-08-08T12:00:00.000Z
Last seen: 2026-08-08T12:00:00.000Z
Enter fullscreen mode Exit fullscreen mode

The timestamps and fingerprint vary between runs. The alert is sanitized before it reaches the notifier.

Why grouping matters

A single failing dependency can generate hundreds of identical errors. Sending every copy immediately makes alerts harder to use and can create unnecessary notification work.

By default, Wotchi groups matching errors and applies a cooldown. The example above uses alertThreshold: 1 only to make local testing immediate. For a real service, the default policy is usually a better starting point.

Wotchi also redacts sensitive values before grouping, logging, or transmission. This is useful for errors that may include request data, tokens, URLs, or provider responses.

Send alerts to Telegram

Console output is enough for local development. For a small self-hosted workflow, you can add Telegram:

import {
  createWotchi,
  telegramNotifier,
} from "@futurewindai/wotchi";

const requiredEnv = (name) => {
  const value = process.env[name];

  if (!value) {
    throw new Error(`${name} must be configured`);
  }

  return value;
};

const wotchi = createWotchi({
  service: "orders-api",
  environment: "production",
  notifiers: [
    telegramNotifier({
      botToken: requiredEnv("WOTCHI_TELEGRAM_BOT_TOKEN"),
      chatId: requiredEnv("WOTCHI_TELEGRAM_CHAT_ID"),
    }),
  ],
});
Enter fullscreen mode Exit fullscreen mode

Keep the bot token and chat ID in environment variables. Never commit them to source control.

Wotchi also provides a generic HTTPS webhook notifier for teams that already have an internal alerting endpoint.

What Wotchi is—and is not

Wotchi is useful when you want a lightweight alerting layer inside a Node.js process:

  • low-noise, grouped error alerts
  • redaction before processing and delivery
  • bounded notification work
  • console, Telegram, and HTTPS webhook destinations
  • Express and NestJS adapters
  • the same capture path for HTTP handlers, workers, and queue processors

It is not a replacement for a complete observability platform. It does not provide a hosted dashboard, durable incident history, distributed tracing, paging workflows, or cross-replica grouping. Grouping and cooldown state are kept in one process and reset when that process restarts.

If you need dashboards, long-term retention, traces, or coordinated incident response, keep using a full observability platform and treat Wotchi as a focused alerting layer.

Try it and tell me what you think

Install the beta:

npm install @futurewindai/wotchi@beta
Enter fullscreen mode Exit fullscreen mode

Wotchi is open source and maintained by FutureWind AI. If you try it, I would especially like feedback about the alert format, redaction rules, and the integrations that would be most useful to you.

Top comments (0)