ViriSIM � Webhooks

Overview

ViriSIM webhooks allow you to send AI input/output pairs for compliance auditing. Unlike traditional webhooks where we send data to you, you send data to us - and we return a submission ID immediately. Audit results are then available in your dashboard.

Simple flow: Your app → POST to ViriSIM API → Receive submission_id → View results in dashboard

Endpoint

POST https://analyzecompliance-vrbinbrbkq-uc.a.run.app

All webhook requests must be sent as POST requests to this endpoint.

Authentication

Every request must include a valid API key in the request header.

X-API-Key: sk-viri-your-api-key-here
Content-Type: application/json

Security: Never expose your API key in client-side code. Always use environment variables or secure backend proxies.

Request Body

The request body must be a JSON object with the following structure:

{
  "user_id": "string",                    // Required: Your unique user identifier
  "company_name": "string",               // Required: Your organization name
  "use_case": "string",                   // Required: Primary use case
  "timestamp": "ISO 8601 date",           // Required: Current timestamp(new Date())
  "your_company_user_id": "string",       // Optional: Your internal user ID
  "your_company_user_session_id": "string", // Optional: Session ID for context
  "model_version": "string",              // Optional: Your AI model version
  "input": {
    "value": "string",                    // Required: Raw user input
    "format": "text|json",                // Required: "text" or "json"
    "country": "string"                   // Required: User's country
  },
  "output": {
    "value": "string",                    // Required: Raw AI output
    "format": "text|json",                // Required: "text" or "json"
    "country": "string"                   // Required: Your country
  }
}

Field Reference

Field	Type	Required	Description
`user_id`	string	✓	Your unique user identifier
`company_name`	string	✓	Your organization name
`use_case`	string	✓	Primary use case (e.g., "Customer Support")
`timestamp`	ISO 8601	✓	Current timestamp - do not modify (new Date())
`your_company_user_id`	string	✗	Your internal user ID for filtering
`your_company_user_session_id`	string	✗	Session ID for context analysis
`model_version`	string	✗	Your AI model version for traceability
`input.value`	string	✓	Raw user input to your AI
`input.format`	string	✓	`"text"` or `"json"`
`input.country`	string	✓	User's country or `"global"`
`output.value`	string	✓	Raw AI-generated output
`output.format`	string	✓	`"text"` or `"json"`
`output.country`	string	✓	Your country of business or `"global"`

Response

Success Response (200)

{
  "submission_id": "VIRI-0001234Xabcde",
  "message": "Success, entry undergoing audit.",
  "status": "success"
}

Error Responses

Status	Error Message	Solution
401	`API key required in X-API-Key header`	Add your API key to the request header
401	`Unauthorized access!`	Invalid or inactive API key - generate a new one
403	`Insufficient Tokens`	Purchase more tokens from Pricing → Buy Tokens
403	`No Subscription`	Activate the Free Plan or purchase a Premium plan
400	`Tokens above the limit of 2k`	Your input+output exceeds 2,000 tokens - truncate before sending
400	`user_id required in request body`	Add the required `user_id` field

Code Examples

curl -X POST https://analyzecompliance-vrbinbrbkq-uc.a.run.app \
  -H "X-API-Key: sk-viri-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_12345",
    "company_name": "Example Corp",
    "use_case": "Customer Support",
    "timestamp": new Date(),
    "your_company_user_id": "internal_001",
    "your_company_user_session_id": "session_abc",
    "model_version": "gpt-4",
    "input": {
        "value": "How do I delete my account?",
        "format": "text",
        "country": "Germany"
    },
    "output": {
        "value": "To delete your account, go to settings...",
        "format": "text",
        "country": "global"
    }
}'

// ViriSIM Webhook - JavaScript/Fetch
async function sendAudit(userInput, aiOutput) {
    const response = await fetch('https://analyzecompliance-vrbinbrbkq-uc.a.run.app', {
        method: 'POST',
        headers: {
            'X-API-Key': 'sk-viri-your-api-key-here',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            user_id: "user_12345",
            company_name: "Example Corp",
            use_case: "Customer Support",
            timestamp: new Date(),
            your_company_user_id: "internal_001",
            your_company_user_session_id: "session_abc",
            model_version: "gpt-4",
            input: {
                value: userInput,
                format: "text",
                country: "Germany"
            },
            output: {
                value: aiOutput,
                format: "text",
                country: "global"
            }
        })
    });
    
    const result = await response.json();
    
    if (response.ok) {
        console.log(` Audit submitted: ${result.submission_id}`);
        console.log(` View results in I/O Logs dashboard`);
    } else {
        console.error(` Error: ${result.error}`);
    }
    
    return result;
}

// Example usage
sendAudit(
    "How do I delete my account?",
    "To delete your account, go to settings..."
);

import requests
from datetime import datetime

def send_audit(user_input, ai_output):
    url = "https://analyzecompliance-vrbinbrbkq-uc.a.run.app"
    headers = {
        "X-API-Key": "sk-viri-your-api-key-here",
        "Content-Type": "application/json"
    }
    
    payload = {
        "user_id": "user_12345",
        "company_name": "Example Corp",
        "use_case": "Customer Support",
        "timestamp": new Date(),
        "your_company_user_id": "internal_001",
        "your_company_user_session_id": "session_abc",
        "model_version": "gpt-4",
        "input": {
            "value": user_input,
            "format": "text",
            "country": "Germany"
        },
        "output": {
            "value": ai_output,
            "format": "text",
            "country": "global"
        }
    }
    
    response = requests.post(url, json=payload, headers=headers)
    result = response.json()
    
    if response.ok:
        print(f" Audit submitted: {result['submission_id']}")
    else:
        print(f" Error: {result.get('error', 'Unknown error')}")
    
    return result

# Example
send_audit(
    "How do I delete my account?",
    "To delete your account, go to settings..."
)

const https = require('https');

function sendAudit(userInput, aiOutput) {
    const data = JSON.stringify({
        user_id: "user_12345",
        company_name: "Example Corp",
        use_case: "Customer Support",
        timestamp: new Date(),
        your_company_user_id: "internal_001",
        your_company_user_session_id: "session_abc",
        model_version: "gpt-4",
        input: {
            value: userInput,
            format: "text",
            country: "Germany"
        },
        output: {
            value: aiOutput,
            format: "text",
            country: "global"
        }
    });

    const options = {
        hostname: 'https://analyzecompliance-vrbinbrbkq-uc.a.run.app',
        method: 'POST',
        headers: {
            'X-API-Key': 'sk-viri-your-api-key-here',
            'Content-Type': 'application/json',
            'Content-Length': data.length
        }
    };

    const req = https.request(options, (res) => {
        let body = '';
        res.on('data', chunk => body += chunk);
        res.on('end', () => {
            const result = JSON.parse(body);
            if (res.statusCode === 200) {
                console.log(` Audit submitted: ${result.submission_id}`);
            } else {
                console.error(` Error: ${result.error}`);
            }
        });
    });
    
    req.on('error', (e) => console.error(`Request error: ${e.message}`));
    req.write(data);
    req.end();
}

// Example
sendAudit(
    "How do I delete my account?",
    "To delete your account, go to settings..."
);

Testing Your Webhook

Before integrating into production, test your webhook using curl or a tool like Postman:

curl -X POST https://analyzecompliance-vrbinbrbkq-uc.a.run.app \
  -H "X-API-Key: sk-viri-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "test_user",
    "company_name": "Test Corp",
    "use_case": "Testing",
    "timestamp": new Date(),
    "input": {
        "value": "This is a test input",
        "format": "text",
        "country": "global"
    },
    "output": {
        "value": "This is a test output",
        "format": "text",
        "country": "global"
    }
}'

Pro tip: Save your submission_id response. You'll use it to find the audit result in your dashboard under I/O Logs.

Best Practices

Don't await the audit: The API returns immediately with a submission_id. Don't block your users waiting for audit completion.
Store submission IDs: Keep the returned ID to reference the audit result later in your dashboard.
Handle errors gracefully: Implement retry logic for failed requests (network issues, rate limits).
Use environment variables: Never hardcode API keys in your source code.
Monitor token usage: Check your Analytics dashboard to track token consumption.
Keep payloads under 2k tokens: Larger inputs will be rejected.

Webhooks