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

> Configure OmniRoute webhooks for usage and quota alerts using the CLI or dashboard. Secure your events with HMAC signature verification for reliable notifications.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-07-28

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/011_webhooks.sql). The [`src/lib/db/webhooks.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/webhooks.ts).

```bash
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:

```javascript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/webhookDispatcher.ts).

## Key Source Files for Webhook Configuration

- **[`src/lib/webhookDispatcher.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/webhookDispatcher.ts)** ([view source](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/src/lib/webhookDispatcher.ts)) – Core dispatcher that matches events to subscriber URLs, signs payloads, and manages retries.
- **[`src/lib/db/webhooks.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/webhooks.ts)** ([view source](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/src/lib/db/webhooks.ts)) – Database model for the `webhooks` table, used by both the CLI and the dashboard wizard.
- **[`src/lib/db/webhookDeliveries.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/webhookDeliveries.ts)** ([view source](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/src/lib/db/webhookDeliveries.ts)) – Tracks every delivery attempt, response status, and retry count.
- **[`src/lib/db/migrations/011_webhooks.sql`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/migrations/011_webhooks.sql)** ([view source](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/src/lib/db/migrations/011_webhooks.sql)) – Creates the initial `webhooks` table with URL, method, secret, and enabled flag.
- **[`src/lib/db/migrations/069_webhook_deliveries.sql`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/migrations/069_webhook_deliveries.sql)** ([view source](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/src/lib/db/migrations/069_webhook_deliveries.sql)) – Creates the `webhook_deliveries` table for audit and retry tracking.
- **[`src/lib/db/migrations/070_webhooks_kind_metadata.sql`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/migrations/070_webhooks_kind_metadata.sql)** ([view source](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/src/lib/db/migrations/070_webhooks_kind_metadata.sql)) – Adds the `kind` column that stores supported event identifiers.
- **`bin/cli/commands/webhooks.mjs`** ([view source](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/bin/cli/commands/webhooks.mjs)) – Implements the `omniroute webhook create`, `list`, and `get` commands.
- **[`tests/unit/webhook-event-descriptions.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tests/unit/webhook-event-descriptions.test.ts)** ([view source](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/tests/unit/webhook-event-descriptions.test.ts)) – Validates the human-readable descriptions for each event kind, including usage and quota alerts.
- **[`tests/unit/cli-webhooks-commands.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tests/unit/cli-webhooks-commands.test.ts)** ([view source](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.49/tests/unit/cli-webhooks-commands.test.ts)) – 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/webhookDispatcher.ts) and validated by the test suite in [`tests/unit/webhook-event-descriptions.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tests/unit/webhook-event-descriptions.test.ts).

### Does OmniRoute retry failed webhook deliveries?

Yes. The [`src/lib/webhookDispatcher.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.