Skip to main content
POST
/
v1
/
webhooks
curl -X POST https://api.playgent.com/v1/webhooks \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/playgent",
    "events": ["run.completed", "run.failed", "evaluation.completed", "optimization.completed"],
    "secret": "whsec_your_secret_key"
  }'
{
  "webhook_id": "wh_abc123",
  "url": "https://your-app.com/webhooks/playgent",
  "events": ["run.completed", "run.failed", "evaluation.completed", "optimization.completed"],
  "active": true
}

Documentation Index

Fetch the complete documentation index at: https://playgent.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Register a webhook endpoint to receive real-time notifications for test runs, evaluations, and optimizations.

Supported Events

EventDescription
run.completedTest run finished successfully
run.failedTest run failed
evaluation.completedEvaluation finished
optimization.completedPrompt optimization finished
url
string
required
Webhook endpoint URL (must be HTTPS)
events
array
required
Events to subscribe to
secret
string
required
Secret for signature verification (use for validating webhook authenticity)
webhook_id
string
required
Webhook identifier
url
string
required
Webhook URL
events
array
required
Subscribed events
active
boolean
required
Whether webhook is active
curl -X POST https://api.playgent.com/v1/webhooks \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/playgent",
    "events": ["run.completed", "run.failed", "evaluation.completed", "optimization.completed"],
    "secret": "whsec_your_secret_key"
  }'
{
  "webhook_id": "wh_abc123",
  "url": "https://your-app.com/webhooks/playgent",
  "events": ["run.completed", "run.failed", "evaluation.completed", "optimization.completed"],
  "active": true
}

Webhook Payload

When an event occurs, Playgent sends a POST request to your webhook URL:
{
  "event": "run.failed",
  "timestamp": "2024-12-16T10:00:00Z",
  "data": {
    "run_id": "run_def456",
    "test_case_id": "tc_xyz789",
    "test_case_name": "Refund Request Flow",
    "failure_summary": "Turn 2 failed: Faithfulness score 0.45 below threshold 0.70"
  }
}

Verifying Signatures

Verify webhook authenticity using the X-Playgent-Signature header:
import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)