Notifications

What this is for

Settings → Notifications lets you push gateway events to any HTTPS endpoint and create alert rules that fire into those endpoints when conditions cross a threshold. Use it to feed SIEM tools, page on-call, drop budget warnings into Slack, or replicate audit events into your own pipeline. The page has two sections: Alert Rules (conditions that trigger notifications) and Webhook Endpoints (where the notifications go).

Options

Webhook Endpoints

Create Webhook form:

Field	Notes
Name	Display label (e.g. `Slack Notifications`).
URL	HTTPS endpoint that receives the POST (e.g. `https://example.com/webhook`).
Events	Pick from the webhook event catalog (see Available events). Leave all unchecked to subscribe to every event.
Signing secret	Generated automatically. Used to compute the `X-Webhook-Signature` HMAC header.
Timeout (ms)	How long the gateway waits before declaring a delivery failed.
Max Retries	Maximum retry attempts on 5xx and network errors (exponential backoff).

Available events

The Events picker lists the events below by name, with a search box. Leave every box unchecked to subscribe the endpoint to all of them. Extra event IDs (optional) takes any additional ids, comma- or newline-separated, for events not in the list. Some events are in the catalog but nothing on the gateway sends them yet. They are marked Not sent yet below. You can subscribe to them, but the endpoint receives nothing for them.

Traffic & latency

Event	ID	When it fires
Request Completed	`request.completed`	After every successful LLM request.
Request Failed	`request.failed`	An LLM request failed: no provider could be selected, the provider has no usable API key, the provider is not allowed for the key or application, or the provider call failed or timed out.
Rate Limited	`request.rate_limited`	A request hit an API key, application, or organization rate limit.
Request Timeout	`request.timeout`	Not sent yet. Upstream or gateway timed out before a response.
Request Cancelled	`request.cancelled`	Not sent yet. Client disconnected or generation was cancelled.
Latency Threshold	`latency.threshold`	Not sent yet. p95/p99 or moving average exceeded your SLA.
Usage Spike	`usage.spike`	Not sent yet. Abnormal request volume compared with the recent baseline.

Tokens & quotas

Event	ID	When it fires
Token Budget Warning	`tokens.budget_warning`	An API key or team budget was exceeded and the request was blocked. Does not fire before the limit is reached.
Quota Warning	`quota.warning`	An API key or team request quota was exceeded and the request was blocked.

Providers & models

Event	ID	When it fires
Provider Down	`provider.down`	Not sent yet. Provider health check failed.
Provider Recovered	`provider.recovered`	Not sent yet. Provider came back online.
Provider Degraded	`provider.degraded`	Not sent yet. Elevated errors or latency, but not fully unavailable.
Model Unavailable	`model.unavailable`	The requested model is not allowed for the API key or application. Does not fire when a provider is down.
Model Quota Exceeded	`model.quota_exceeded`	Not sent yet. Provider-side quota or capacity limit hit.
Model Deprecated	`model.deprecated`	Not sent yet. Configured model marked deprecated.

Routing & cache

Event	ID	When it fires
Routing Fallback	`routing.fallback`	Not sent yet. A routing rule fell back to a secondary target.
Routing Rule Failed	`routing.rule_failed`	Not sent yet. No healthy target matched after rule evaluation.
Cache Anomaly	`cache.anomaly`	Not sent yet. Unusual cache bypass or miss burst.

Spend

Event	ID	When it fires
Spend Threshold	`spend.threshold`	A request was blocked because an API key, team, or application budget was exceeded.
Spend Anomaly	`spend.anomaly`	Not sent yet. Spend deviates from the forecast or normal pattern.

Security & guardrails

Event	ID	When it fires
Guardrail Blocked	`guardrail.blocked`	Every guardrail event: blocks, plus flagged, masked, fail-open, and error events.
Prompt Injection Signal	`guardrail.prompt_injection`	Prompt-injection detections only.
Guardrail block (log type)	`guardrail_block`	Same as Guardrail Blocked: every guardrail event, under the `guardrail_block` log type id.
Guardrails blocked (plural)	`guardrails.blocked`	Same as Guardrail Blocked: every guardrail event, alternate id.
Security guardrail block	`security.guardrail_block`	Same as Guardrail Blocked: every guardrail event, `security.*` id.
Content policy blocked	`content_policy.blocked`	Same as Guardrail Blocked: every guardrail event, policy and content-filter id.

Despite the names, these five ids are not limited to blocks. An endpoint subscribed to more than one of them receives each guardrail event once.

MCP

Event	ID	When it fires
MCP Server Unreachable	`mcp.server_unreachable`	An MCP server health check or handshake failed.
MCP Tool Denied	`mcp.tool_denied`	A tool call was denied by policy.
MCP Scan Completed	`mcp.scan_completed`	Not sent yet. An MCP security scan finished.

API keys

Event	ID	When it fires
API Key Created	`key.created`	A new API key was created.
API Key Revoked	`key.revoked`	An API key was revoked.
Key Rate Limited	`key.rate_limited`	Fires together with Rate Limited, on every rate-limited request (API key, application, or organization limit).
Key Expiring Soon	`key.expiring_soon`	Not sent yet. Rotation or expiry reminder.
Key Suspected Compromise	`key.compromised_suspected`	An abnormal usage pattern on a key warrants review.

Audit & access

Event	ID	When it fires
Config Change	`audit.config_change`	Gateway rate-limit, cache, or alert settings, or the routing strategy, were changed.
Login Failed	`audit.login_failed`	A gateway login failed with invalid credentials. Fires on every failed attempt for an existing user.
Permission Denied	`audit.permission_denied`	An API key or application was denied access to an MCP server.
Sensitive Resource Access	`audit.resource_access`	Not sent yet. Sensitive configuration or an export was accessed.

Repositories

Event	ID	When it fires
New repository findings	`repo.findings_detected`	A scheduled or manual repository scan found new findings at or above the minimum severity. The first scan of a repository sends one baseline summary. See Repository findings alerts.

Organization & platform

Event	ID	When it fires
Team Membership Changed	`team.membership_changed`	A gateway user was created or deleted, or their team or role changed.
Webhook Delivery Failed	`webhook.delivery_failed`	Not sent yet. Repeated failures delivering to a webhook endpoint.

Repositories

Event	ID	When it fires
Repository Scan Failed	`repo.scan_failed`	A scheduled or manual scan of a GitHub or Azure DevOps repository failed for a reason you can fix. Sent by Guardway cloud, not the gateway. See Repository scan failures.

When one gateway event matches several ids an endpoint subscribes to, the endpoint gets a single delivery. Its X-Webhook-Event header carries the first matching id.

Repository scan failures

repo.scan_failed tells you when Discovery could not scan a repository and the fix is on your side. Guardway cloud sends it, not the gateway, and it checks for new failures every 10 minutes. When it is sent

Guardway lost access to the repository, for example the GitHub App can’t access it (HTTP 4xx) or the Azure DevOps connection lost access. GitHub rate limits are on Guardway’s side and are not sent.
The repository is too large to scan.
The repository type is unsupported.

It covers scheduled and manual scans of GitHub and Azure DevOps repositories. Failures on Guardway’s side are not sent to you. Pull request scans are not covered either: they are reported on the PR check. It is sent once per repository and failure reason. After a later scan of that repository succeeds, the next failure is sent again. A repository still failing after 30 days is reported again as a reminder. At most 5 failures per organization are sent per 10-minute run, and the rest follow in later runs. Where it goes

Every connected Slack workspace, to its default channel.
Every enabled webhook endpoint with repo.scan_failed checked in its event list.

Alert rules are not used for this event, and PagerDuty, Opsgenie, Teams, and email channels do not receive it. Because Guardway cloud makes the request, the webhook URL must be a public https:// address. Private or internal addresses and http:// URLs are refused. Up to 3 attempts for timeouts, network errors, 5xx, 408 and 429, with a 10 second timeout per attempt. Other 4xx responses and redirects are not retried, and a Retry-After above 5 seconds ends delivery. Headers

Header	Value
`Content-Type`	`application/json`
`X-Webhook-Event`	`repo.scan_failed`
`X-Webhook-ID`	The webhook endpoint id.
`X-Webhook-Signature`	`sha256=` and the lowercase hex HMAC-SHA256 of the exact body, keyed with the webhook secret. Only sent when the webhook has a secret.

Payload

{
  "event": "repo.scan_failed",
  "org_id": "<uuid>",
  "scan_id": "<uuid>",
  "repository": {
    "name": "acme/payments-api",
    "url": "https://github.com/acme/payments-api"
  },
  "error_kind": "download",
  "error": "The GuardWay GitHub App can't access this repository (GitHub returned HTTP 404). ...",
  "failed_at": "2026-10-26T09:12:44.000Z",
  "dashboard_url": "https://app.guardway.ai/inventory/repositories/<id>"
}

Field	Notes
`error_kind`	`download` (Guardway could not fetch the repository), `too_large`, or `unsupported_repo`.
`error`	Human-readable reason, up to 500 characters.
`repository.url`	The repository’s `https://` URL.
`dashboard_url`	Opens the repository’s page in Guardway, or the Repositories list when the scan isn’t linked to a Discovery repository.

In the dashboard the event appears under the Repositories category as Repository Scan Failed.

Repository findings alerts

repo.findings_detected tells you when a GitHub or Azure DevOps repository scan finds something new. It is available to organizations as it rolls out. When it fires

After a manual or scheduled repository scan completes. Pull request scans do not fire it: they report on the pull request itself.
The first completed scan of a repository sends one baseline summary of everything it found.
Later scans report only new findings: those not present in the repository’s previous two completed scans. Using two scans means one degraded scan does not make Guardway announce everything again. Compliance (OWASP MCP) findings are matched by risk id.
Scans keep up to 1000 findings per scanner. A finding that falls outside that cap and later returns can be reported again.

Minimum severity and repositories. Only findings at or above the minimum severity count; the default is High. By default an alert covers all repositories; add a repository filter to narrow it. A scan whose findings are all below the minimum sends nothing. Where it goes

Slack, through an alert rule: in Create Alert, set Rule type to New repository findings.
Webhooks, through an alert rule (Rule type set to New repository findings) or a webhook subscription to repo.findings_detected. An endpoint subscribed without an alert rule always uses a minimum severity of High and covers all repositories; use an alert rule to change either.
PagerDuty, Opsgenie, Microsoft Teams and email notification channels do not support this event.
Each destination is notified at most once per scan. When several rules or subscriptions reach the same destination, the first one that qualifies sends. Cooldown does not apply.

Webhook delivery. Guardway sends the POST from the cloud, not from your gateway, so the per-endpoint Timeout and Max Retries settings do not apply.

The URL must use https and resolve to a public address. Private, loopback and link-local addresses, .local names and single-label hosts are refused.
Redirects are not followed; a 3xx response counts as a failed delivery.
Any non-2xx response (including 4xx) or network error is retried, for 3 attempts in total, each with a 10 second timeout, waiting 1 s and then 3 s between attempts. A Retry-After header is honoured up to 5 s. There are no retries after the third attempt.
Requests are signed like any other event: X-Webhook-Signature, X-Webhook-Event and X-Webhook-ID. See Verifying the signature.

Payload

Field	Meaning
`event_type`	Always `repo.findings_detected`.
`event_id`	Unique id of this notification.
`kind`	`baseline` for the first scan of a repository, `new_findings` afterwards.
`alert_rule_id`, `alert_rule_name`	The alert rule that sent it. Omitted when the delivery comes from a webhook subscription.
`min_severity`	The minimum severity applied: `critical`, `high`, `medium`, `low` or `info`.
`repository`	`id`, `name` (for example `acme/api`) and `provider` (`github` or `azure-devops`).
`scan_id`	The scan that produced the findings.
`counts`	Findings per severity. Only severities at or above `min_severity` appear.
`findings`	Up to 5 findings at or above `min_severity`, each with `severity`, `title`, `source`, `file_path` and `line_number` (`null` when not applicable).
`total_findings`	Number of findings in the scan, including those below `min_severity` and those not listed in `findings`.
`dashboard_url`	Link to the repository in the dashboard.
`triggered_at`	ISO 8601 timestamp.

Example body:

{
  "event_type": "repo.findings_detected",
  "event_id": "ev1",
  "kind": "new_findings",
  "alert_rule_id": "abcdef0123456789",
  "alert_rule_name": "Repo alerts",
  "min_severity": "high",
  "repository": { "id": "r1", "name": "acme/api", "provider": "github" },
  "scan_id": "s1",
  "counts": { "critical": 1, "high": 2 },
  "findings": [
    { "severity": "critical", "title": "t1", "source": "sca", "file_path": null, "line_number": null },
    { "severity": "high", "title": "t2", "source": "sca", "file_path": null, "line_number": null },
    { "severity": "high", "title": "t3", "source": "sca", "file_path": null, "line_number": null }
  ],
  "total_findings": 7,
  "dashboard_url": "https://app.guardway.ai/inventory/repositories/r1",
  "triggered_at": "2026-10-26T12:00:00.000Z"
}

Alert Rules

Create Alert form:

Field	Notes
Name	Display label (e.g. `High Error Rate`).
Condition	Free-text condition expression (e.g. `error_rate > 5%`).
Threshold	Numeric or human threshold the condition compares against (e.g. `100 requests`).
Severity	`Critical`, `Warning`, or `Info`.
Cooldown	`1 minute`, `5 minutes`, `15 minutes`, `1 hour`, or `24 hours`.
Webhook endpoint	Pick from the configured endpoints. Required.

For New repository findings (repo.findings_detected), Condition and Threshold are replaced by Minimum severity (default High) and Repositories (all by default), and Cooldown does not apply (it is shown disabled: “Each scan alerts once.”). To use it, set Rule type to New repository findings in Create Alert. See Repository findings alerts.

Delivery guarantees

HMAC signing — every request includes an X-Webhook-Signature header, sha256= followed by the hex HMAC-SHA256 of the body, keyed with the signing secret.
Event header — X-Webhook-Event carries the subscribed event id the delivery matched.
Retries — for gateway-delivered events, exponential backoff on 5xx and network errors, up to Max Retries. repo.findings_detected is sent from the cloud with its own retry policy; see Repository findings alerts.
Per-webhook filters — only the events selected on each endpoint are delivered.
Audit trail — every delivery attempt (success or failure) is recorded in Audit Log.

How to configure

Create a webhook endpoint

Open Settings → Notifications from the dashboard sidebar, scroll to Webhook Endpoints, click Create Webhook. Fill Name, URL, Events, Signing secret, Timeout, and Max Retries. Save.

Verify on your receiver

Trigger one of the selected events (e.g. an MCP call for request.completed) and confirm your endpoint received a signed POST.

Create an alert rule

Scroll to Alert Rules, click Create Alert. Set Name, Condition, Threshold, Severity, Cooldown, and pick the Webhook endpoint the alert should notify.

Test it

Force the condition (e.g. exceed an API key’s request quota from Playground) and confirm both the gateway log and your endpoint show the delivery.

Verifying the signature

Compute HMAC-SHA256 over the raw request body using your webhook Signing secret, hex-encode it, prefix it with sha256=, and compare the result to the X-Webhook-Signature header. Reject the delivery if they don’t match.

import crypto from "node:crypto";

// rawBody: the exact request body as a Buffer or string, before JSON parsing
function isValid(rawBody, header, secret) {
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(header ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Repository findings — what a repository scan finds.
Budgets and Alerts — the budget.threshold and budget.exceeded events and which subscriptions receive them.
Audit Log — every webhook delivery attempt is recorded here.
Integrations — first-party integrations that don’t need a webhook.

Getting Started

Platform

Gateway

Inventory

Endpoint AI Risk

Resources

API Reference

What this is for

Options

Webhook Endpoints

Available events

Traffic & latency

Tokens & quotas

Providers & models

Routing & cache

Spend

Security & guardrails

MCP

API keys

Audit & access

Repositories

Organization & platform

Repositories

Repository scan failures

Repository findings alerts

Payload

Alert Rules

Delivery guarantees

How to configure

Verifying the signature

​What this is for

​Options

​Webhook Endpoints

​Available events

​Traffic & latency

​Tokens & quotas

​Providers & models

​Routing & cache

​Spend

​Security & guardrails

​MCP

​API keys

​Audit & access

​Repositories

​Organization & platform

​Repositories

​Repository scan failures

​Repository findings alerts

​Payload

​Alert Rules

​Delivery guarantees

​How to configure

​Verifying the signature

​Related

What this is for

Options

Webhook Endpoints

Available events

Traffic & latency

Tokens & quotas

Providers & models

Routing & cache

Spend

Security & guardrails

MCP

API keys

Audit & access

Repositories

Organization & platform

Repositories

Repository scan failures

Repository findings alerts

Payload

Alert Rules

Delivery guarantees

How to configure

Verifying the signature

Related