Webhooks

Send real-time AI interactions to ViriSIM for compliance auditing

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",              // Required: Your AI model version
  
  "your_company_signature": "string",     // Optional: ECDSA signature proving your company signed this I/O before submission
"your_company_signing_key_id": "string", // Optional: KMS key path used to verify the signature
  "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

FieldTypeRequiredDescription
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
your_company_signature string ✗ ECDSA signature proving your company signed this I/O before submission
your_company_signing_key_id string ✗ KMS key path used to verify the signature
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

StatusError MessageSolution
401API key required in X-API-Key headerAdd your API key to the request header
401Unauthorized access!Invalid or inactive API key - generate a new one
403 Insufficient Tokens Purchase more tokens from Pricing → Buy Tokens
403No SubscriptionActivate the Free Plan or purchase a Premium plan
400Tokens above the limit of 2kYour input+output exceeds 2,000 tokens - truncate before sending
400user_id required in request bodyAdd 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",
    "your_company_signature": "MEUCIQDxK9cF8mN2vR5jH7sT3wB6dL0pA1qY4uW8eR2oG5tSJgIgV7kM3nB4cD5fG6hJ8kL0mN1pQ2rS3tU4vW5xY6zA7==",
"your_company_signing_key_id": "projects/customer-project-123/locations/europe-west3/keyRings/compliance-signing-ring/cryptoKeys/audit-signing-key/cryptoKeyVersions/1",
    "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",
            "your_company_signature": "MEUCIQDxK9cF8mN2vR5jH7sT3wB6dL0pA1qY4uW8eR2oG5tSJgIgV7kM3nB4cD5fG6hJ8kL0mN1pQ2rS3tU4vW5xY6zA7==",
"your_company_signing_key_id": "projects/customer-project-123/locations/europe-west3/keyRings/compliance-signing-ring/cryptoKeys/audit-signing-key/cryptoKeyVersions/1",
            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",
        "your_company_signature": "MEUCIQDxK9cF8mN2vR5jH7sT3wB6dL0pA1qY4uW8eR2oG5tSJgIgV7kM3nB4cD5fG6hJ8kL0mN1pQ2rS3tU4vW5xY6zA7==",
"your_company_signing_key_id": "projects/customer-project-123/locations/europe-west3/keyRings/compliance-signing-ring/cryptoKeys/audit-signing-key/cryptoKeyVersions/1",
        "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",
       "your_company_signature": "MEUCIQDxK9cF8mN2vR5jH7sT3wB6dL0pA1qY4uW8eR2oG5tSJgIgV7kM3nB4cD5fG6hJ8kL0mN1pQ2rS3tU4vW5xY6zA7==",
"your_company_signing_key_id": "projects/customer-project-123/locations/europe-west3/keyRings/compliance-signing-ring/cryptoKeys/audit-signing-key/cryptoKeyVersions/1", 
        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(),
      "model_version": "test-model",
  "your_company_signature": "test_signature", 
"your_company_signing_key_id": "test_signing_id",
    "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.

 Security Note: The examples above are for illustration only. Never hardcode API keys in your code. Use environment variables instead — e.g., process.env.VIRIDEED_API_KEY

Ready to Start Auditing?

Go to ViriSIM, get your API key and run your first compliance audit in under 30 minutes.

Go to ViriSIM