From fc5b6d30a557862a4c7bd6b619221cf06634fdd6 Mon Sep 17 00:00:00 2001 From: Akhil Menon Date: Wed, 2 Sep 2026 14:59:43 +0530 Subject: [PATCH 1/2] Added proxy request webhook guardrail feature integration documentation in BYOG, Guardrail Checks and Changelog --- changelog/enterprise.mdx | 4 +- .../guardrails/bring-your-own-guardrails.mdx | 55 ++++++++++++++++++- .../guardrails/list-of-guardrail-checks.mdx | 2 +- 3 files changed, 56 insertions(+), 5 deletions(-) diff --git a/changelog/enterprise.mdx b/changelog/enterprise.mdx index 17ed46250..14371a5c7 100644 --- a/changelog/enterprise.mdx +++ b/changelog/enterprise.mdx @@ -50,9 +50,9 @@ Set `SERVER_MODE=unified` to run the AI Gateway and MCP Gateway on a single port ### Webhook Guardrails for Proxy Requests -The webhook guardrail can now run on proxy (`/v1/*`) requests via an opt-in `executeOnProxy` parameter, letting you block passthrough traffic based on a custom webhook check. +The webhook guardrail can now run on proxy (`/v1/*`) requests via an opt-in `executeOnProxy` parameter, letting you block passthrough traffic based on a custom webhook check. Webhooks operate in deny-only mode on proxy routes (transforms are ignored) and require a JSON content type — non-JSON requests skip the check. -[Guardrails Documentation](/product/guardrails/list-of-guardrail-checks) +[Webhook Guardrails Documentation](/integrations/guardrails/bring-your-own-guardrails#webhook-guardrails-on-proxy-requests) ### Provider Updates diff --git a/integrations/guardrails/bring-your-own-guardrails.mdx b/integrations/guardrails/bring-your-own-guardrails.mdx index 2fbf69255..4c47a0d21 100644 --- a/integrations/guardrails/bring-your-own-guardrails.mdx +++ b/integrations/guardrails/bring-your-own-guardrails.mdx @@ -34,6 +34,7 @@ In the Guardrail configuration UI, you'll need to provide: | **Timeout** | Maximum wait time for webhook response | `number` (ms) | | **Fail on Error** | Treat a non-200 response or a timeout as a failed check | `boolean` | | **Forward Headers** | Client headers to forward to your webhook | `string[]` | +| **Execute on Proxy** | Run this webhook on proxy (`/v1/*`) requests. When enabled, the webhook operates in deny-only mode — transforms are ignored. Default: `false` | `boolean` | #### Webhook URL @@ -74,7 +75,8 @@ Skip the portal entirely and pass the webhook check inline in the request config "webhookURL": "https://guardrails.example.com/pre-check", "headers": { "Authorization": "Bearer WEBHOOK_TOKEN" }, "timeout": 5000, - "failOnError": true + "failOnError": true, + "executeOnProxy": true } }] }], @@ -221,7 +223,15 @@ Portkey sends comprehensive information about the AI request to your webhook: Portkey provider slug. Example: `openai`, `azure-openai`, etc. - Type of request: `chatComplete`, `complete`, or `embed` + Type of request: `chatComplete`, `complete`, `embed`, or `proxy` + + HTTP metadata for the request. Present when the webhook runs on a proxy route. + + HTTP method (e.g., `POST`, `GET`) + Request path (e.g., `/v1/moderations`) + Content-Type header value (e.g., `application/json`) + + Custom metadata passed with the request. Can come from: 1) the `x-portkey-metadata` header, 2) default API key settings, or 3) workspace defaults. When the hook is triggered: `beforeRequestHook` or `afterRequestHook` @@ -390,6 +400,10 @@ Return a verdict without modifying the request/response: Modify the user's request before it reaches the LLM provider: + +Request transformations are not applied for proxy requests. Webhook guardrails on proxy routes operate in deny-only mode. + + ```json @@ -447,6 +461,10 @@ Modify the user's request before it reaches the LLM provider: Modify the LLM's response before it reaches the user: + +Response transformations are not applied for proxy requests. Webhook guardrails on proxy routes operate in deny-only mode. + + ```json @@ -545,6 +563,39 @@ Your webhook will receive these headers alongside `Content-Type` and any custom +## Webhook Guardrails on Proxy Requests + +By default, webhook guardrails only run on standard routes (`/v1/chat/completions`, `/v1/embeddings`, etc.). To run a webhook guardrail on proxy (`/v1/*`) passthrough requests, set `executeOnProxy: true` on the webhook check. + +```json Inline config for proxy webhook +{ + "before_request_hooks": [{ + "id": "proxy-content-check", + "type": "guardrail", + "deny": true, + "checks": [{ + "id": "default.webhook", + "parameters": { + "webhookURL": "https://guardrails.example.com/proxy-check", + "executeOnProxy": true + } + }] + }] +} +``` + +### How It Works + +- Your webhook receives the full JSON request body in `request.json`, along with `requestInfo` containing the HTTP method, path, and content type. +- Both `before_request_hooks` and `after_request_hooks` are supported on proxy routes. +- The webhook can allow or deny the request based on the payload content. + +### Limitations + +- **Deny-only mode**: `transformedData` returned by the webhook is ignored for proxy requests, since the webhook cannot know the upstream schema of an opaque passthrough body. +- **JSON only**: Proxy requests with non-JSON content types (binary, FormData, etc.) skip the webhook entirely. +- **All checks must opt in**: If a guardrail contains multiple checks, every check must be a `default.webhook` with `executeOnProxy: true`. Mixed guardrails (e.g., webhook + regex match) are skipped on proxy routes — split them into separate guardrails. + ## Important Implementation Notes 1. **Complete Transformations**: When using `transformedData`, include all fields in your transformed object, not just the changed portions. diff --git a/product/guardrails/list-of-guardrail-checks.mdx b/product/guardrails/list-of-guardrail-checks.mdx index 4eed52a11..49d19bcf0 100644 --- a/product/guardrails/list-of-guardrail-checks.mdx +++ b/product/guardrails/list-of-guardrail-checks.mdx @@ -233,7 +233,7 @@ Basic deterministic guardrails are ideal for quick, hard-coded validations that #### Extensibility | Guardrail Check | Description | Parameters | Supported On | | :--- | :--- | :--- | :--- | -| **Webhook** | Makes a webhook request for custom guardrails. | `webhookURL`: string, `headers`: json | Input, Output | +| **Webhook** | Makes a webhook request for custom guardrails. | `webhookURL`: string, `headers`: json, `executeOnProxy`: boolean | Input, Output | | **Log** | Makes a request to a log URL and always gives true as the verdict. | `logURL`: string, `headers`: json | Output only | From 0faee95521cf2cc5843c8671d62fefbf34d900be Mon Sep 17 00:00:00 2001 From: Akhil Menon Date: Wed, 2 Sep 2026 15:22:04 +0530 Subject: [PATCH 2/2] Formatting related changes --- changelog/enterprise.mdx | 2 +- integrations/guardrails/bring-your-own-guardrails.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/changelog/enterprise.mdx b/changelog/enterprise.mdx index 14371a5c7..30cc876c5 100644 --- a/changelog/enterprise.mdx +++ b/changelog/enterprise.mdx @@ -50,7 +50,7 @@ Set `SERVER_MODE=unified` to run the AI Gateway and MCP Gateway on a single port ### Webhook Guardrails for Proxy Requests -The webhook guardrail can now run on proxy (`/v1/*`) requests via an opt-in `executeOnProxy` parameter, letting you block passthrough traffic based on a custom webhook check. Webhooks operate in deny-only mode on proxy routes (transforms are ignored) and require a JSON content type — non-JSON requests skip the check. +The webhook guardrail can now run on proxy (`/v1/*`) requests via an opt-in `executeOnProxy` parameter, letting you block passthrough traffic based on a custom webhook check. Webhooks operate in deny-only mode on proxy routes (transforms are ignored) and require a JSON content type, as non-JSON requests skip the check. [Webhook Guardrails Documentation](/integrations/guardrails/bring-your-own-guardrails#webhook-guardrails-on-proxy-requests) diff --git a/integrations/guardrails/bring-your-own-guardrails.mdx b/integrations/guardrails/bring-your-own-guardrails.mdx index 4c47a0d21..f14644ba6 100644 --- a/integrations/guardrails/bring-your-own-guardrails.mdx +++ b/integrations/guardrails/bring-your-own-guardrails.mdx @@ -34,7 +34,7 @@ In the Guardrail configuration UI, you'll need to provide: | **Timeout** | Maximum wait time for webhook response | `number` (ms) | | **Fail on Error** | Treat a non-200 response or a timeout as a failed check | `boolean` | | **Forward Headers** | Client headers to forward to your webhook | `string[]` | -| **Execute on Proxy** | Run this webhook on proxy (`/v1/*`) requests. When enabled, the webhook operates in deny-only mode — transforms are ignored. Default: `false` | `boolean` | +| **Execute on Proxy** | Run webhooks on proxy requests in deny-only mode (transforms are ignored) | `boolean` | #### Webhook URL