Skip to main content
This endpoint creates a new webhook endpoint that will receive real-time notifications when requests are logged to Helicone. Configure sampling rates and property filters to control which events trigger the webhook.

​
Use Cases

  • Set up real-time monitoring for LLM requests
  • Integrate Helicone data with external systems
  • Build custom alerting and notification systems
  • Stream request data to analytics platforms

​
Request Body

​
destination
string
required
The URL endpoint where webhook events will be sent. Must be a valid HTTPS URL.
​
config
object
required
Configuration object for the webhook
​
config.sampleRate
number
Percentage of requests to send to the webhook (0-100). Default: 100
​
config.propertyFilters
array
Array of property filters to match specific requests
​
config.propertyFilters[].key
string
required
Property key to filter on (e.g., “model”, “user_id”)
​
config.propertyFilters[].value
string
required
Property value to match
​
includeData
boolean
Whether to include full request/response data in webhook payload. Default: true

​
Response

Returns a Result object with the created webhook data.
​
data
object
Created webhook information (structure depends on database response)
​
error
string | null
Error message if the request failed, null on success

​
Example Request

curl --request POST \
  --url https://api.helicone.ai/v1/webhooks \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "destination": "https://example.com/webhook",
    "config": {
      "sampleRate": 100,
      "propertyFilters": [
        {
          "key": "model",
          "value": "gpt-4"
        }
      ]
    },
    "includeData": true
  }'

​
Example Response

{
  "data": {},
  "error": null
}

​
Webhook Payload

When your webhook is triggered, it will receive a POST request with the following structure: 
{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "gpt-4",
  "created_at": "2024-01-15T10:30:00Z",
  "properties": {
    "user_id": "user_123"
  },
  "request": { /* full request data if includeData: true */ },
  "response": { /* full response data if includeData: true */ }
}

​
Webhook Verification

All webhook requests include an HMAC signature in the X-Helicone-Signature header. Use the hmac_key from the webhook list endpoint to verify the signature and ensure the request is authentic.

​
Error Responses

{
  "data": null,
  "error": "Sample rate must be between 0 and 100"
}

{
  "data": null,
  "error": "Property filters must be an array of objects with key and value properties"
}