Docs → Platforms → Custom Webhook

Custom Webhook Integration Guide

Send events from any platform, language, or system using a simple HTTP POST request.

How it works in 30 seconds

1.Create an agent in OpsViz → get your webhook URL (10 seconds)
2.Add one step to your Custom Webhook workflow → paste the URL (2 minutes)
3.See costs, tokens, and alerts in real time (instantly)

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.

Set up with AI — copy and paste

The fastest way to add OpsViz monitoring is to paste this prompt into your AI assistant. It sets everything up automatically.

Using any AI assistant

Paste this into Claude Code, ChatGPT, or any coding AI with your code attached:

I want to add OpsViz monitoring to my application. Add a non-blocking HTTP POST call to [WEBHOOK_URL] after each AI API call. The JSON body should contain: event_type ("task.completed", "task.failed", or "task.timeout"), model (the model name string), tokens_in (integer), tokens_out (integer), cost_usd (float, can be 0 if unknown), duration_ms (integer), agent_name (string label for this workflow). The request must never block my main code or cause failures if OpsViz is unreachable. Use fire-and-forget pattern appropriate for my language.

Prerequisites

An OpsViz account with an agent created
Your OpsViz webhook URL
Any HTTP client (curl, fetch, requests, axios, etc.)

Send a POST request

The simplest possible integration — a single HTTP POST:

curl -X POST [WEBHOOK_URL] \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "task.completed",
    "agent_name": "My AI Workflow",
    "status": "success"
  }'

Add token and cost data (optional)

{
  "event_type": "task.completed",
  "agent_name": "My AI Workflow",
  "model": "your-model-name",
  "tokens_in": 1000,
  "tokens_out": 500,
  "cost_usd": 0.015,
  "duration_ms": 2300,
  "status": "success",
  "metadata": {
    "any_key": "any_value"
  }
}

Fire and forget — non-blocking

Best practice: send events asynchronously so monitoring never blocks your agent:

# Python example with fire-and-forget
import threading, requests

def report(event_type, **kwargs):
    def _send():
        try:
            requests.post(OPSVIZ_URL,
                json={"event_type": event_type, **kwargs},
                timeout=3)
        except: pass
    threading.Thread(target=_send, daemon=True).start()

That's it!

Events will appear on your OpsViz dashboard as they arrive. Check the webhook reference for full payload options.