Webhook Payload Reference

Every event sent to OpsViz uses the same JSON payload format. Only event_type is required — everything else is optional.

Privacy note: OpsViz receives only operational metadata — event type, token counts, model name, cost, and duration. Your prompts, responses, user data, and AI provider credentials are never sent to OpsViz.

Endpoint

POST [WEBHOOK_URL]

Content-Type: application/json. The webhook URL itself serves as authentication — keep it private.

Full Payload Schema

{
  "event_type": "task.completed",   // REQUIRED
  "agent_name": "Support Bot",       // optional: display name override
  "model": "claude-sonnet-4-6",      // optional: for auto cost calculation
  "tokens_in": 1240,                 // optional: input tokens
  "tokens_out": 890,                 // optional: output tokens
  "cost_usd": 0.03,                  // optional: overrides auto-calculation
  "duration_ms": 2400,               // optional: task execution time
  "status": "success",               // optional: success|error|timeout|cancelled
  "metadata": {                      // optional: any key-value pairs
    "task_id": "ticket-4521",
    "workflow": "customer-support",
    "user_id": "user_123"
  }
}

Event Types

Type	When to use
task.started	Agent begins executing a task (optional — useful for duration tracking)
task.completed	Task finished successfully. Include tokens/cost for accurate billing.
task.failed	Task errored or was rejected. Include status: "error".
task.timeout	Task exceeded its time limit. Include duration_ms if known.

Cost Calculation

OpsViz uses a 3-tier fallback to calculate cost:

1.If cost_usd is in the payload → use it directly (most accurate)
2.If model + tokens_in + tokens_out → auto-calculate from pricing database (35+ models)
3.If model is unrecognised → store event flagged as "uncosted", prompt user to add pricing

Batch Endpoint

Send up to 100 events in a single request:

POST [WEBHOOK_URL]/batch

[
  { "event_type": "task.completed", "model": "gpt-4o", "tokens_in": 500 },
  { "event_type": "task.failed", "status": "error", "duration_ms": 1200 }
]

Response

Successful single event returns 201 Created:

{
  "id": "evt_abc123",
  "created_at": "2026-04-09T10:30:00Z",
  "cost_usd": 0.0024,
  "cost_calculated": true
}

Error Codes

Code	Meaning
201	Event accepted and stored
400	Invalid payload (missing event_type or validation error)
401	Invalid agent ID or webhook secret
403	Agent is paused or archived
429	Monthly event limit reached — upgrade your plan
500	Server error — retry with exponential backoff