[view as .md]

Webhooks

Webhooks let you react to modelux events in your own infrastructure: budget alerts, config changes, provider health transitions, request anomalies, and scheduled-experiment runs.

Event types

  • budget.threshold_reached
  • budget.exceeded
  • routing_config.updated
  • routing_config.created
  • routing_config.deleted
  • provider.health_changed
  • api_key.revoked
  • request.anomaly_detected
  • experiment.completed — a scheduled experiment’s run finished. Fires on every run, regardless of whether any threshold was breached. Use it as the firehose for your own observability pipeline.
  • experiment.regression_detected — a scheduled experiment’s latest run breached one or more configured thresholds (cost / latency / error rate / judge-worse). Fires only on the breach, not every subsequent run while the regression persists; pair it with experiment.completed if you want both. The payload includes a signal_key that correlates the event with the matching in-app signal on the overview page.

Endpoint setup

  1. Open Integrations -> Webhooks in the dashboard.
  2. Click Add endpoint. Enter the destination URL.
  3. Select which event types to subscribe to.
  4. modelux generates a signing secret. Save it to verify incoming payloads.

Signature verification

Every delivery includes an X-Modelux-Signature header with an HMAC-SHA256 of the raw body using your signing secret.

import crypto from "crypto";

function verify(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

Delivery & retries

  • Deliveries run asynchronously through a durable queue
  • On non-2xx response or timeout: retried with exponential backoff up to 24h
  • The dashboard shows per-delivery status, payload, response body, and a replay button for manual redelivery

Slack-compatible format

Set the endpoint URL to a Slack webhook URL. modelux detects it and formats the payload as a Slack message automatically.