How to Configure Webhooks for Usage and Quota Alert Events in OmniRoute

To configure usage and quota alert webhooks in OmniRoute, register a webhook URL with the usage-alert and quota-alert event kinds via the CLI or dashboard, and verify the optional HMAC signature in your receiver.

OmniRoute ships a built-in webhooks framework that dispatches real-time HTTP notifications when system thresholds are crossed. Learning how to configure webhooks for usage and quota alert events ensures your billing and capacity monitors stay synchronized with actual gateway consumption. This guide walks through the CLI commands, database schema, and dispatcher logic as implemented in diegosouzapw/OmniRoute.

Overview of the OmniRoute Webhook Architecture

The webhook pipeline in OmniRoute is composed of three layers: persistent storage, event dispatching, and delivery tracking. When a usage or quota threshold is breached, the system emits an event that the Webhook Dispatcher (src/lib/webhookDispatcher.ts) routes to all matching, enabled endpoints.

Webhook Storage and Schema

Webhook definitions live in the SQLite-backed webhooks table defined by migration 011_webhooks.sql. The src/lib/db/webhooks.ts module provides the CRUD helpers that the CLI and dashboard use to insert and update records. Migration 070_webhooks_kind_metadata.sql adds the kind column, which stores the comma-separated event identifiers—such as usage-alert and quota-alert—that a subscription listens for.

Event Dispatching and Delivery

The dispatcher reads enabled rows from src/lib/db/webhooks.ts, compares the emitted event against the stored kind metadata, and hands off work to the delivery layer. src/lib/db/webhookDeliveries.ts persists every attempt in the webhook_deliveries table, while the dispatcher executes the HTTP request and implements exponential back-off retries for non-2xx responses. If a secret is configured, the dispatcher computes an HMAC-SHA256 signature and attaches it as the x-omniroute-signature header.

Configuring a Usage and Quota Alert Webhook

You can register a webhook through the CLI command suite located in bin/cli/commands/webhooks.mjs or through the dashboard UI. Both interfaces ultimately call the same underlying database helpers in src/lib/db/webhooks.ts.

Using the CLI to Create the Webhook

Run the omniroute webhook create sub-command with the target URL and the specific event kinds for usage and quota monitoring. The following example also supplies an optional secret to enable payload signing:

omniroute webhook create \
  --url https://example.com/omniroute-alerts \
  --events usage-alert,quota-alert \
  --secret mySuperSecret123

• --url is the HTTPS endpoint that OmniRoute will POST to.
• --events accepts a comma-separated list; the identifiers usage-alert and quota-alert are defined in src/lib/webhookDispatcher.ts.
• --secret is optional. When provided, the dispatcher hashes the JSON payload with HMAC-SHA256 and sends the digest in the x-omniroute-signature header.

Validating the Stored Configuration

After creation, confirm that the record was written correctly. You can retrieve it with the CLI or inspect the webhooks table directly via src/lib/db/webhooks.ts.

omniroute webhook get <webhook-id>

Receiving and Verifying Alerts in Your Application

When a usage or quota threshold is crossed, OmniRoute POSTs a JSON payload to your endpoint. The body includes an event field—set to usage-alert or quota-alert—and a data object containing the current consumption value, limit, timestamp, and affected account or API key.

Below is a minimal Node.js receiver that verifies the HMAC signature before processing the alert:

import crypto from "node:crypto";
import express from "express";

const app = express();
app.use(express.json());

app.post("/omniroute-alerts", (req, res) => {
  const signature = req.header("x-omniroute-signature");
  const secret = "mySuperSecret123";
  const payload = JSON.stringify(req.body);

  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

  if (signature !== expected) {
    console.warn("Invalid webhook signature");
    return res.sendStatus(401);
  }

  console.log("Received OmniRoute alert:", req.body);
  res.sendStatus(200);
});

app.listen(3000, () => console.log("Webhook listener running on :3000"));

• Replace mySuperSecret123 with the exact secret you passed to omniroute webhook create.
• The dispatcher always sends the payload as JSON, so express.json() is sufficient.
• Return a 2xx status code to acknowledge receipt; any other status triggers the retry logic in src/lib/webhookDispatcher.ts.

Key Source Files for Webhook Configuration

• src/lib/webhookDispatcher.ts (view source) – Core dispatcher that matches events to subscriber URLs, signs payloads, and manages retries.
• src/lib/db/webhooks.ts (view source) – Database model for the webhooks table, used by both the CLI and the dashboard wizard.
• src/lib/db/webhookDeliveries.ts (view source) – Tracks every delivery attempt, response status, and retry count.
• src/lib/db/migrations/011_webhooks.sql (view source) – Creates the initial webhooks table with URL, method, secret, and enabled flag.
• src/lib/db/migrations/069_webhook_deliveries.sql (view source) – Creates the webhook_deliveries table for audit and retry tracking.
• src/lib/db/migrations/070_webhooks_kind_metadata.sql (view source) – Adds the kind column that stores supported event identifiers.
• bin/cli/commands/webhooks.mjs (view source) – Implements the omniroute webhook create, list, and get commands.
• tests/unit/webhook-event-descriptions.test.ts (view source) – Validates the human-readable descriptions for each event kind, including usage and quota alerts.
• tests/unit/cli-webhooks-commands.test.ts (view source) – End-to-end CLI tests that assert correct persistence of event lists.

Summary

• Register a webhook for usage-alert and quota-alert with omniroute webhook create or the dashboard UI.
• The dispatcher in src/lib/webhookDispatcher.ts routes events by matching the kind metadata stored in the webhooks table.
• Delivery attempts are logged in webhook_deliveries, and failed requests are retried automatically with exponential back-off.
• Secure your endpoint by supplying a --secret during creation and validating the x-omniroute-signature header with HMAC-SHA256.

Frequently Asked Questions

What event identifiers should I use for usage and quota alerts?

Use the exact identifiers usage-alert and quota-alert. These strings are defined in src/lib/webhookDispatcher.ts and validated by the test suite in tests/unit/webhook-event-descriptions.test.ts.

Does OmniRoute retry failed webhook deliveries?

Yes. The src/lib/webhookDispatcher.ts module implements automatic retries with exponential back-off whenever your endpoint returns a non-2xx status. Each attempt is recorded in the webhook_deliveries table via src/lib/db/webhookDeliveries.ts.

How do I secure my webhook endpoint?

Pass a --secret string when you run omniroute webhook create. The dispatcher will then include an HMAC-SHA256 digest of the JSON payload in the x-omniroute-signature header, which your receiver can verify using the same secret.

Can I configure webhooks through the dashboard instead of the CLI?

Yes. The dashboard wizard under Settings → Webhooks uses the same src/lib/db/webhooks.ts helpers that the CLI commands in bin/cli/commands/webhooks.mjs call, so both methods produce identical database records and behavior.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}