@agstack/notification-webhook

Enterprise-grade webhook notification plugin for AGStack

A reference implementation for every AGStack notification plugin. Delivers notifications asynchronously through the AGStack Runtime Worker Pool without ever blocking HTTP requests.

Features

• Async Pipeline — Runtime → Queue → Worker → Filter → Format → Retry → Delivery
• Filtering — Severity, environment, hostname, tags, route, custom expressions
• Rate Limiting — Per-minute, per-hour, burst, cooldown, deduplication, aggregation
• Retry Queue — Exponential backoff, jitter, max retries, dead letter queue
• Payload Formats — JSON, Compact, Minimal, Detailed, Custom Templates
• Authentication — Bearer tokens, API keys, Basic auth, custom headers
• Security — HTTPS by default, certificate validation, HMAC signing, secret masking
• Metrics — Delivery latency, success rate, failure tracking, queue depth
• Health Check — Plugin status, pending queue, retry queue, failure reasons

Installation

npm install @agstack/notification-webhook

Quick Start

import { NotificationWebhookPlugin, DEFAULTS, validateConfig } from "@agstack/notification-webhook";
import { createRuntime } from "@agstack/logger";

const runtime = createRuntime({
  plugins: [
    () => {
      const plugin = new NotificationWebhookPlugin();
      runtime.registerPlugin("notification-webhook", plugin, {
        options: validateConfig({
          url: "https://hooks.example.com/alerts",
          method: "POST",
          format: "compact",
          auth: { type: "bearer", bearerToken: process.env.WEBHOOK_SECRET },
          filter: { minSeverity: "warning" },
          retry: { maxRetries: 3 },
        }),
      });
      return plugin;
    },
  ],
});

await runtime.start();

// Notifications are sent automatically by the Runtime
// when security threats, errors, or alerts occur

Manual Notification

const plugin = runtime.getPlugin("notification-webhook");
await plugin.send({
  channel: "security",
  title: "SQL Injection Detected",
  message: "Blocked injection attempt from IP 10.0.0.1",
  severity: "critical",
  transactionId: "tx-123",
  metadata: {
    source: "express",
    route: "/api/users",
    ip: "10.0.0.1",
  },
});

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | url | string | (required) | Webhook endpoint URL | | method | POST \| PUT \| PATCH | "POST" | HTTP method | | timeoutMs | number | 10000 | Request timeout | | format | PayloadFormat | "json" | Payload format | | auth.type | AuthType | "none" | Authentication type | | retry.maxRetries | number | 3 | Maximum retry attempts | | rateLimit.maxPerMinute | number | 60 | Max notifications/minute | | rateLimit.maxPerHour | number | 1000 | Max notifications/hour | | filter.minSeverity | SeverityLevel | "info" | Minimum severity level |

Architecture

Runtime Event → Notification Plugin
                     ↓
                Filter Engine
                     ↓ (if passed)
                Rate Limiter
                     ↓ (if allowed)
                Payload Formatter
                     ↓
                Webhook Client
                     ↓
            ┌─── Success ───→ Metrics
            │
            └─── Failure ───→ Retry Queue
                                  ↓
                     Exponential Backoff
                                  ↓
                     Delivery Attempt
                                  ↓
                     Max Retries → DLQ

API

NotificationWebhookPlugin

| Method | Description | |--------|-------------| | send(notification) | Send a single notification asynchronously | | sendBatch(notifications) | Send multiple notifications | | health() | Get plugin health and metrics |

License

MIT