Create Webhook

Register a webhook for events

POST /v1/webhooks

cURL

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"
  }'

Response

{
  "webhook_id": "wh_abc123",
  "url": "https://your-app.com/webhooks/playgent",
  "events": ["run.completed", "run.failed", "evaluation.completed", "optimization.completed"],
  "active": true
}

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

Supported Events

Event	Description
run.completed	Test run finished successfully
run.failed	Test run failed
evaluation.completed	Evaluation finished
optimization.completed	Prompt 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

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"
  }'

Response

{
  "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)