> ## Documentation Index
> Fetch the complete documentation index at: https://docs.requesty.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sample Requests

> Automatically mirror sampled requests and responses to your webhook for analysis and monitoring

> [!NOTE]
>
> Sample Requests (experimental) allows you to automatically forward a percentage of your API requests and responses to a webhook endpoint for analysis, monitoring, and quality assurance.
>
> > [!NOTE]
> >
> > **[View request logs](https://app.requesty.ai/logs)** in the Requesty Console.

## Overview

The Sample Requests feature enables you to capture a configurable percentage of chat completion requests and responses, forwarding them to your webhook URL for detailed analysis. This is useful for:

* **Quality Monitoring**: Review AI responses for quality assurance
* **Analytics**: Analyze request patterns and response characteristics

## How to use

Request sampling is configured using the `sample` object within the `requesty` field when sending chat completion requests:

```json theme={"dark"}
{
  "requesty": {
    "sample": {
      "webhook_url": "https://your-webhook-url.com/endpoint",
      "sample_ratio": 0.1
    }
  }
}
```

### Parameters

* **`webhook_url`** (required): The HTTPS endpoint URL where sampled requests and responses will be sent via HTTP POST
* **`sample_ratio`** (required): A float between 0 and 1 (inclusive) representing the percentage of requests to sample
  * `0.0`: No requests sampled
  * `0.1`: 10% of requests sampled
  * `1.0`: 100% of requests sampled

Note: Your webhook could respond with a JSON payload with a `feedback` object containing string key-value pairs. And the entire object will be attached as `feedback` to the logs of the sampled request. All keys can only contain \[a-z, A-Z, 0-9, -, \_] and are up to 128 chars and all values must be valid strings representing either float, int64 or strings of the same constraints.

## A concrete example

Chat completion request

```bash theme={"dark"}
curl --request POST \
  --url https://router.requesty.ai/v1/chat/completions \
  --header 'Authorization: Bearer YOUR_REQUESTY_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "openai/gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": "hello"
    }
  ],
  "requesty": {
    "sample": {
      "webhook_url": "https://your-webhook-url.com/endpoint",
      "sample_ratio": 1
    }
  }
}'
```

When a request is sampled, your webhook receives a POST request with the following structure where `request` and `response` conform to OpenAI Chat Completion API.

```json theme={"dark"}
{
  "request_id": "...",
  "request": {
    "messages": [
      {
        "content": "hello",
        "role": "user"
      }
    ],
    "model": "openai/gpt-4o"
  },
  "response": {
    "choices": [
      {
        "finish_reason": "stop",
        "index": 0,
        "message": {
          "content": "Hello! How can I help you today?",
          "role": "assistant"
        }
      }
    ],
    "created": 1761758842,
    "id": "...",
    "model": "openai/gpt-4o",
    "object": "chat.completion",
    "usage": {
      "completion_tokens": 15,
      "prompt_tokens": 10,
      "total_tokens": 25,
      "cost": 0
    },
    "base_resp": {
      "status_code": 0,
      "status_msg": ""
    }
  }
}
```

## Verifying sampled webhooks

If your organization has a webhook signing secret, each sampled webhook is signed with it. The `webhook-id` header matches the payload's `request_id`, and the `X-Requesty-Event` header is `sample.request`. See [Webhook Signatures](/features/webhook-signatures) for how to verify the signature.

## Webhook response

An example of a valid webhook response.

```json theme={"dark"}
{
  "feedback": {
    "thumbs": "up",
    "rating": "5",
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.