Gateway webhook notifications

Connect your alerting service

Workspace owners and administrators can open Gateway → Alerts → Get notified. Notifications work in both Monitoring & Audit and Enforcement. Start with blocked requests and uncertain outcomes; add flagged requests when you want notifications for Monitoring concerns.

1. Enter an HTTPS destination you own or are authorized to use. It must be reachable on the public internet using the standard HTTPS port, without redirects, query parameters, or URL credentials. Private network endpoints are not supported.
2. Select events, enter a reason, and save. Saving pauses notifications and creates a signing secret shown only once. Store it in your receiver's server-side secret store.
3. Verify signatures in your receiver and return a 2xx response within eight seconds after durably accepting the message.
4. Select Send test. Refresh deliveries if necessary. After a successful test, select Enable notifications. Only new matching requests are included; historical requests are not backfilled.

Test delivery confirms that the destination returned a successful HTTP response. It cannot prove that the receiver verified the signature, paged a person, or completed downstream processing. Check those in your receiving service before relying on alerts. Email and direct Slack integrations are not part of this beta; use a receiver that understands this webhook format.

Events and privacy

Event types are gateway.blocked, gateway.flagged, gateway.uncertain, and gateway.test. A pending request is not notified until an outcome is available. An uncertain outcome takes priority over the request's decision. Blocked requests can occur in either mode when Gateway stops an unsafe or invalid dispatch. Alerts never change the deterministic decision.

Each message contains id, type, version (currently 1), created_at, and workspace_id. Request events also contain request with id, agent_id, tool_name, rule, policy_version, mode, decision, outcome, and created_at. Test messages contain test: true and a synthetic message, without a request.

Arguments, tool responses, credentials, and administrator reasons are not sent. Tool names and workspace/agent identifiers are still organizational metadata: send only to authorized destinations. Treat all message values as untrusted display text. Link back to the workspace's Gateway Requests page to investigate, add a scoped exception or deny rule, or block an agent.

Verify the signature

Headers are X-FooGuard-Delivery, X-FooGuard-Timestamp (Unix seconds), and X-FooGuard-Signature (v1= followed by lowercase hexadecimal HMAC-SHA256). The signed bytes are the timestamp, a period, and the exact raw UTF-8 request body. The secret is used as its displayed text, not decoded from hex.

This Node.js example verifies the raw body before parsing JSON. Enforce a 64 KiB request limit in your HTTP server and keep its clock synchronized. The delivery header must match the signed payload ID.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(rawBody, headers, secret) {
  const timestamp = headers.get('x-fooguard-timestamp') ?? '';
  const signature = headers.get('x-fooguard-signature') ?? '';
  if (!/^\d{10}$/.test(timestamp) ||
      Math.abs(Date.now() / 1000 - Number(timestamp)) > 300 ||
      !/^v1=[a-f0-9]{64}$/.test(signature)) return false;
  const expected = createHmac('sha256', secret)
    .update(timestamp + '.').update(rawBody).digest();
  if (!timingSafeEqual(expected, Buffer.from(signature.slice(3), 'hex'))) return false;
  const event = JSON.parse(rawBody.toString('utf8'));
  return event.id === headers.get('x-fooguard-delivery');
}

Reject malformed JSON and invalid signatures. After verification, validate the version and event fields, and atomically store the delivery ID with your work item. Return 2xx for an already accepted ID. This prevents duplicate actions if a response is lost or a worker restarts. Keep deduplication records at least as long as your delivery history: administrators can manually retry old failures. Never automatically retry the underlying agent tool call just because a notification arrives; an uncertain tool outcome may already have executed.

Delivery, failure and recovery

A separate scheduler checks for work about every five minutes. Scheduling can be delayed; this beta has no guaranteed notification latency. The Alerts page shows the last completed delivery run and warns after 15 minutes without one. Refresh to see current status. Contact support if scheduler delay persists.

Delivery is at least once when successful, not exactly once or guaranteed. Non-2xx responses (including redirects), timeouts, invalid DNS destinations, and connection failures retry up to five total attempts. Minimum backoffs are one minute, five minutes, 15 minutes, and one hour; actual attempts wait for a scheduler run. An interrupted attempt can be repeated after its two-minute lease expires. A response lost after acceptance can cause a duplicate notification.

The current scheduler claims up to 100 deliveries per run, at most 50 per workspace, with 25 concurrent sends. Bursts can create a backlog. The pending count includes that backlog. This beta is intended for modest alert volume; avoid enabling flagged events for every high-volume request without considering the receiving service's capacity.

Use Show failed deliveries to inspect the latest 50 failures, fix the receiver, then Retry. Retrying moves the item out of the failed view so older failures can be reached on refresh. It starts a new set of five attempts with the same delivery ID. Only failures for the current destination configuration can be retried. HTTP status codes and safe error categories are shown; response bodies are not stored.

Pause notifications cancels queued request alerts. A send already in flight may arrive. Resuming affects new events only. Save changes & rotate secret cancels pending and failed deliveries, replaces the destination configuration and secret, and requires another successful test before enabling. Update your receiver immediately; in-flight requests signed with the previous secret may still arrive. If the secret is lost, rotate it. Remove destination deletes the destination and encrypted secret and cancels queued work.

Configuration changes are recorded in the workspace audit log. Delivery metadata remains until workspace deletion, alongside Gateway request history. Removing a destination does not erase delivery history. External receivers control their own retention. Learned behavior/anomaly notifications and email remain outside this release.