Portkey’s webhook guardrails allow you to integrate your existing guardrail infrastructure with our AI Gateway. This is perfect for teams that have already built custom guardrail pipelines (like PII redaction, sensitive content filtering, or data validation) and want to:

  • Enforce guardrails directly within the AI request flow
  • Make existing guardrail systems production-ready
  • Modify AI requests and responses in real-time

​
How It Works

  1. You add a Webhook as a Guardrail Check in Portkey
  2. When a request passes through Portkey’s Gateway:
    • Portkey sends relevant data to your webhook endpoint
    • Your webhook evaluates the request/response and returns a verdict
    • Based on your webhook’s response, Portkey either allows the request to proceed, modifies it if required, or applies your configured guardrail actions

​
Setting Up a Webhook Guardrail

​
Configure Your Webhook in Portkey App

In the Guardrail configuration UI, you’ll need to provide:

FieldDescriptionType
Webhook URLYour webhook’s endpoint URLstring
HeadersHeaders to include with webhook requestsJSON
TimeoutMaximum wait time for webhook responsenumber (ms)

​
Webhook URL

This should be a publicly accessible URL where your webhook is hosted.

Enterprise Feature: Portkey Enterprise customers can configure secure access to webhooks within private networks.

​
Headers

Specify headers as a JSON object:

{
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}

​
Timeout

The maximum time Portkey will wait for your webhook to respond before proceeding with a default verdict: true.

  • Default: 3000ms (3 seconds)
  • If your webhook processing is time-intensive, consider increasing this value

​
Webhook Request Structure

Your webhook should accept POST requests with the following structure:

​
Request Headers

HeaderDescription
Content-TypeAlways set to application/json
Custom HeadersAny headers you configured in the Portkey UI

​
Request Body

Portkey sends comprehensive information about the AI request to your webhook:

​
Event Types

Your webhook can be triggered at two points:

  • beforeRequestHook: Before the request is sent to the LLM provider
  • afterRequestHook: After receiving a response from the LLM provider
{
    "request": {
        "json": {
            "stream": false,
            "messages": [
                {
                    "role": "system",
                    "content": "You are a helpful assistant"
                },
                {
                    "role": "user",
                    "content": "Say Hi"
                }
            ],
            "max_tokens": 20,
            "n": 1,
            "model": "gpt-4o-mini"
        },
        "text": "Say Hi",
        "isStreamingRequest": false,
        "isTransformed": false
    },
    "response": {
        "json": {},
        "text": "",
        "statusCode": null,
        "isTransformed": false
    },
    "provider": "openai",
    "requestType": "chatComplete",
    "metadata": {
        "_user": "visarg123"
    },
    "eventType": "beforeRequestHook"
}

​
Webhook Response Structure

Your webhook must return a response that follows this structure:

​
Response Body

​
Webhook Capabilities

Your webhook can perform three main actions:

​
Simple Validation

Return a verdict without modifying the request/response:

{
  "verdict": true  // or false if the request violates your guardrails
}

​
Request Transformation

Modify the user’s request before it reaches the LLM provider:

{
  "verdict": true,
  "transformedData": {
    "request": {
      "json": {
        "messages": [
          {
            "role": "system",
            "content": "You are a helpful assistant. Do not provide harmful content."
          },
          {
            "role": "user",
            "content": "Original user message"
          }
        ],
        "max_tokens": 100,
        "model": "gpt-4o"
      }
    }
  }
}

​
Response Transformation

Modify the LLM’s response before it reaches the user:

{
  "verdict": true,
  "transformedData": {
    "response": {
      "json": {
        "id": "chatcmpl-123",
        "object": "chat.completion",
        "created": 1741592832,
        "model": "gpt-4o-mini",
        "choices": [
          {
            "index": 0,
            "message": {
              "role": "assistant",
              "content": "I've filtered this response to comply with our content policies."
            },
            "finish_reason": "stop"
          }
        ],
        "usage": {
          "prompt_tokens": 23,
          "completion_tokens": 12,
          "total_tokens": 35
        }
      },
      "text": "I've filtered this response to comply with our content policies."
    }
  }
}

​
Passing Metadata to Your Webhook

You can include additional context with each request using Portkey’s metadata feature:

// In your API request to Portkey
"x-portkey-metadata": {"user": "john", "context": "customer_support"}

This metadata will be forwarded to your webhook in the metadata field. Learn more about metadata.

​
Important Implementation Notes

  1. Complete Transformations: When using transformedData, include all fields in your transformed object, not just the changed portions.

  2. Independent Verdict and Transformation: The verdict and any transformations are independent. You can return verdict: false while still returning transformations.

  3. Default Behavior: If your webhook fails to respond within the timeout period, Portkey will default to verdict: true.

  4. Event Type Awareness: When implementing transformations, ensure your webhook checks the eventType field to determine whether it’s being called before or after the LLM request.

​
Example Implementation

Check out our Guardrail Webhook implementation on GitHub:

Guardrail Webhook Implementation

​
Get Help

Building custom webhooks? Join the Portkey Discord community for support and to share your implementation experiences!