Skip to content

Document gateway policy webhooks - #1333

Open
jerm-dro wants to merge 3 commits into
mainfrom
add-policy-webhook-docs
Open

jerm-dro wants to merge 3 commits into
mainfrom
add-policy-webhook-docs

Conversation

@jerm-dro

@jerm-dro jerm-dro commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Description

Adds a how-to page for each gateway's policy webhooks, so operators can send requests to their own policy service.

  • Connector Gateway (connector-gateway/policy-webhooks):
    • Configuring connector-gateway.enterpriseConfig.policyWebhooks: validating and mutating webhooks, match.tools scoping, failure policy, TLS, and HMAC signing.
    • The order the gateway calls webhooks in, and what the client sees when a call is denied.
    • The request and response format, which is the ToolHive webhook format. The page links to the ToolHive webhooks guide and pkg/webhook rather than repeating them, and lists only where the gateway's requests differ.
  • AI Gateway (ai-gateway/policy-webhooks):
    • The two points where a webhook can run, request.received and response.completed, plus required and observation webhooks, and the order they run in after the built-in checks.
    • Configuring ai-gateway-v2.extraHooks: caBundle and tokenProjection for receiver trust, lifecycle.completionHookTimeout, and failure policy and retries.
    • The WebhookReview request and response. Request bodies and usage are passed through as the provider sent them, so the page points receiver authors to each provider's API reference rather than documenting provider formats.
  • Sidebar entries for both pages, and a link to each from the Related information section of the connector policies and model access pages.

Type of change

  • New documentation

Related issues/PRs

  • Closes stacklok/stacklok-enterprise-platform#6295
  • Closes stacklok/stacklok-enterprise-platform#6528
  • Closes stacklok/stacklok-enterprise-platform#6529
  • Documents stacklok/stacklok-enterprise-platform#6530 (Connector Gateway policy webhooks) and stacklok/stacklok-enterprise-platform#6698 (AI Gateway extraHooks)

Submitter checklist

Content and formatting

  • I have reviewed the content for technical accuracy
  • I have reviewed the content for spelling, grammar, and style

Navigation

  • New pages include a frontmatter section with title and description at a minimum
  • Sidebar navigation (sidebars.ts) updated for added, deleted, reordered, or renamed files
  • Redirects added to vercel.json for moved, renamed, or deleted pages (i.e., if the URL slug changed)

Reviewer checklist

Content

  • I have reviewed the content for technical accuracy
  • I have reviewed the content for spelling, grammar, and style

🤖 Generated with Claude Code

Add pages for Connector Gateway and AI Gateway policy webhooks,
and link them from the sidebar and related pages.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings November 14, 2026 01:06
@vercel

vercel Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
docs-website Ready Ready Preview Nov 16, 2026 5:34pm UTC

Request Review

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The documentation overstates ToolHive receiver compatibility and needs to distinguish shared request/response formats from gateway-specific restrictions, particularly the rejection of tool-name patches.

1 open issue
What changed in this PR

Adds policy webhook guides for the Connector Gateway and AI Gateway, helping operators connect their own policy services to gateway request processing.

Changes:

  • Documents webhook configuration, execution order, receiver contracts, and failure handling.
  • Covers authentication, network access, monitoring, and troubleshooting.
  • Adds sidebar entries and links from the existing access-policy guides.
File Description
sidebars.ts Adds navigation entries for both webhook guides.
docs/​connector-gateway/​policy-webhooks.mdx Explains tool-call validation, mutation, and receiver setup.
docs/​connector-gateway/​connector-policies.mdx Links connector access policies to the webhook guide.
docs/​ai-gateway/​policy-webhooks.mdx Explains request and completion hooks, enforcement, and receiver setup.
docs/​ai-gateway/​control-model-access.mdx Links model access controls to the webhook guide.

Review effort: Balanced

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

@amirejaz amirejaz left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for writing this up. I checked the AI Gateway page against the gateway and chart code on main. Most of it is accurate: the field table and its limits, the phase and enforcement rules, the call order after the built-in checks, the WebhookReview field names, the deny-message format, the retry triggers, the completion timeout rules, and the render-time and startup checks all match.

The inline comments cover the places where a customer would be misled or caught out. The ones that matter most are:

  • What a required response.completed webhook does to traffic without usage.
  • The CA-rotation restart.
  • networkPolicy.enabled defaulting to false.
  • Malformed 2xx answers blocking the response.

I haven't reviewed the Connector Gateway page here.

Comment thread docs/ai-gateway/policy-webhooks.mdx Resolved
Comment thread docs/ai-gateway/policy-webhooks.mdx Resolved
Comment thread docs/ai-gateway/policy-webhooks.mdx Resolved
Comment thread docs/ai-gateway/policy-webhooks.mdx Resolved
Comment thread docs/ai-gateway/policy-webhooks.mdx Resolved
Comment thread docs/ai-gateway/policy-webhooks.mdx Resolved
Comment thread docs/ai-gateway/policy-webhooks.mdx Resolved
Comment thread docs/ai-gateway/policy-webhooks.mdx Resolved
Comment thread docs/ai-gateway/policy-webhooks.mdx Resolved
Comment thread docs/ai-gateway/policy-webhooks.mdx Resolved
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown
Contributor

Visual regression failed

The visual job failed, but CI could not produce a compact screenshot summary.

Details were unavailable because the Playwright artifact is unavailable.

Open the failed visual job · Download the full Playwright report

If the change is intentional, a repository collaborator can comment /update-snapshots to regenerate the baselines.

@amirejaz amirejaz left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the quick turnaround. I re-checked bd9e2f8 against the gateway and chart code on main, and every AI Gateway point is addressed accurately. That includes the new includeSubjectClaims row: subject.claims is a string-to-string map, so only string-valued claims are sent. Leaving the other five extraHooks fields out for now makes sense to me. LGTM from the hooks side.

@jerm-dro
jerm-dro requested a review from amirejaz November 16, 2026 18:00

This branch was successfully deployed

1 active deployment
Preview — bd9e2f8b Deployed Nov 16, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants