Generic Webhook

Tasks

Forward audit events, policy denials, budget alerts, and HITL notifications to any HTTP endpoint. Useful for connecting AIControls to internal SIEM systems, custom dashboards, or workflow automation tools.

Configure the webhook

1. Go to Settings → Integrations → Generic Webhook and click Add webhook.
2. Enter your endpoint URL — must be HTTPS and publicly reachable from AIControls servers.
3. Optionally set a signing secret. AIControls will include an X-AIControls-Signature header on every request so you can verify authenticity.
4. Select which event types to send (see below).
5. Click Save. AIControls sends a test POST immediately — confirm your endpoint returns 2xx.

Payload format

All events are delivered as HTTP POST with Content-Type: application/json. The envelope is consistent across event types:

{
  "event_type": "tool_denied",
  "timestamp": "2026-06-30T12:34:56Z",
  "workspace": "your-org",
  "data": { ... }
}

Your endpoint must return a 2xx status within 10 seconds. AIControls retries up to 3 times with exponential backoff on non-2xx or timeout.

Event types

Event type	Triggered when
tool_denied	A policy denies an MCP tool call or LLM request
budget_alert	Org or team spend reaches the configured alert threshold
budget_exceeded	Org or team spend cap is hit — new requests are blocked
hitl_pending	A request is queued for human approval
hitl_resolved	A HITL request is approved or denied
policy_violation	Content safety or PII policy triggers
settings_changed	An app setting (rate limits, budgets, upstreams, OIDC, and similar) is saved through the Settings UI or admin API
policy_fail_open_changed	The policy fail-open setting changes value — flagged separately since it silently changes how policy-evaluator errors are handled
settings_config_shadowed	On boot, config.yaml/Helm sets an app setting that already has a different value saved in the database, so the file value is ignored
exception_approval_requested	A developer submits an exception, model-access, or session budget top-up request that needs approver action — see Approval Workflow
exception_granted	A request is approved and its grant takes effect — single-approver decision or the final co-sign approval
exception_denied	A request is denied, by a single approver or any required co-signer
exception_expired	A granted exception's expiry time passes
exception_revoked	An admin revokes a still-active granted exception early

settings_config_shadowed only fires on Self-Hosted Kubernetes deployments — see Configuration Model for the full deployment-vs-app-setting split.

Signature verification

If you configured a signing secret, each request includes:

X-AIControls-Signature: sha256=<hmac-sha256-hex>

Compute HMAC-SHA256(secret, raw-request-body) and compare. Reject requests where the signature doesn't match.

Troubleshooting

Test delivery failed

Check that your endpoint is publicly reachable over HTTPS and returns 2xx. Firewall rules, self-signed certificates, or redirects (301/302) will cause delivery failures.

Events not arriving

Confirm the event type is enabled in the webhook configuration. Check Settings → Integrations → Webhook → Delivery log for recent attempts and response codes.