Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.toktra.dev/llms.txt

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

Toktra sends HTTP POST requests to your endpoint when events occur — policy violations, budget alerts, lockouts, and more. Webhooks are the fastest way to integrate Toktra events into your own systems.

​
Register a webhook

POST /v1/webhooks
​
url
string
required
Your HTTPS endpoint URL. Must return a 2xx status within 10 seconds.
​
events
array
List of event types to subscribe to. Omit to subscribe to all events.
​
description
string
Optional human-readable label for this webhook.

​
Request

curl -X POST https://api.toktra.io/v1/webhooks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/toktra/events",
    "events": ["policy_violation", "budget_exceeded"],
    "description": "Production alert handler"
  }'

​
Response

{
  "id": "wh1a2b3c-0000-0000-0000-000000000001",
  "url": "https://your-app.example.com/toktra/events",
  "events": ["policy_violation", "budget_exceeded"],
  "description": "Production alert handler",
  "signing_secret": "whsec_abc123...",
  "created_at": "2025-01-15T10:00:00Z"
}
Save the signing_secret immediately — it is only shown once. You will use it to verify incoming webhook payloads.

​
Verify webhook signatures

Every webhook request includes an X-Toktra-Signature header containing an HMAC-SHA256 signature of the raw request body, signed with your signing_secret. Always verify this signature before processing the payload. 
import hmac
import hashlib

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

# In your request handler:
# signature = request.headers.get("X-Toktra-Signature")
# if not verify_signature(request.body, signature, WEBHOOK_SECRET):
#     return 401

​
Event payload format

All webhook payloads share a common envelope: 
{
  "id": "evt_01945b36-4567-7000-8000-000000000001",
  "type": "policy_violation",
  "created_at": "2025-01-15T10:30:00Z",
  "org_id": "a1b2c3d4-0000-0000-0000-000000000000",
  "data": {
    "alert_id": "al1b2c3d-0000-0000-0000-000000000001",
    "severity": "high",
    "user_id": "u1a2b3c4-0000-0000-0000-000000000001",
    "policy_id": "p1a2b3c4-0000-0000-0000-000000000001",
    "provider": "openai",
    "model": "gpt-4",
    "details": {
      "policy_name": "Restrict GPT-4 to Engineering",
      "department": "marketing"
    }
  }
}

​
Event types

Event typeTriggered when
policy_violationA usage policy fires (alert or block action)
budget_exceededAn org or department budget limit is reached
budget_warningSpend reaches 80% of a budget
user_locked_outAn employee is offboarded and access is revoked
anomaly_detectedPre-departure anomaly or unusual usage spike
device_enrolledA new device completes enrollment
device_revokedA device certificate is revoked

​
Retry behavior

If your endpoint returns a non-2xx status or times out, Toktra retries with exponential backoff:
AttemptDelay
1Immediate
21 second
35 seconds
430 seconds
55 minutes
After 5 failed attempts the delivery is marked as failed. You can manually retry failed deliveries from the dashboard or via the API.

​
View delivery logs

GET /v1/webhooks/{id}/deliveries
Returns a paginated list of recent delivery attempts, including HTTP status codes and response bodies.

​
Test a webhook

Send a test event to verify your endpoint is reachable: 
POST /v1/webhooks/{id}/test

curl -X POST https://api.toktra.io/v1/webhooks/wh1a2b3c-0000-0000-0000-000000000001/test \
  -H "Authorization: Bearer YOUR_TOKEN"
Toktra sends a ping event to your endpoint: 
{
  "id": "evt_test_01945b36",
  "type": "ping",
  "created_at": "2025-01-15T10:00:00Z",
  "org_id": "a1b2c3d4-0000-0000-0000-000000000000",
  "data": {}
}