Skip to content
TruthVouch Docs

Webhook Events

Complete reference of all webhook events emitted by TruthVouch, including event types, payloads, and schema examples.

Event Categories

TruthVouch emits events across several categories:

  • Alerts — Governance Gateway detections (PII, injection, toxicity)
  • Certifications — Truth nugget lifecycle and certification
  • Compliance — Regulatory scans and audit events
  • Monitoring — Sentinel agent status and usage
  • Governance — Policy changes and enforcement

Alert Events

alert.detected

Fired when the Governance Gateway detects a policy violation.

When: Immediately when scan matches a rule

Payload:

{
  "event_type": "alert.detected",
  "timestamp": "2024-01-15T10:30:00Z",
  "organization_id": "org-abc123",
  "alert_id": "alert-xyz789",
  "severity": "high",
  "detection_type": "pii",
  "details": {
    "pii_type": "ssn",
    "confidence": 0.95,
    "excerpt": "[redacted]",
    "scan_duration_ms": 45,
    "model": "gpt-4",
    "direction": "response"
  },
  "source": {
    "ip_address": "192.168.1.100",
    "user_id": "user-123",
    "api_key_id": "key-abc"
  },
  "action_taken": "blocked",
  "message": "High-confidence SSN detected in response"
}

alert.resolved

Fired when an alert is manually resolved.

When: Administrator marks alert as resolved in dashboard

Payload:

{
  "event_type": "alert.resolved",
  "timestamp": "2024-01-15T10:35:00Z",
  "organization_id": "org-abc123",
  "alert_id": "alert-xyz789",
  "resolved_by": "admin@company.com",
  "resolution_reason": "false_positive",
  "resolution_notes": "This is a test SSN, not real data"
}

alert.escalated

Fired when an alert is escalated to security team.

When: Manual escalation or automatic based on threshold

Payload:

{
  "event_type": "alert.escalated",
  "timestamp": "2024-01-15T10:36:00Z",
  "organization_id": "org-abc123",
  "alert_id": "alert-xyz789",
  "escalation_level": 2,
  "escalated_to": ["security@company.com", "ciso@company.com"],
  "escalation_reason": "multiple_violations",
  "severity_score": 0.85
}

Certification Events

certification.issued

Fired when a new certification is issued for a truth nugget.

When: Content passes all verification checks

Payload:

{
  "event_type": "certification.issued",
  "timestamp": "2024-01-15T11:00:00Z",
  "organization_id": "org-abc123",
  "certification_id": "cert-abc123",
  "nugget_id": "nugget-xyz789",
  "content_hash": "sha256:abcdef...",
  "verification_method": "human_review",
  "verified_by": "reviewer@company.com",
  "validity_period": {
    "starts_at": "2024-01-15T11:00:00Z",
    "expires_at": "2025-01-15T11:00:00Z"
  },
  "certificate_url": "https://truthvouch.io/certs/cert-abc123",
  "blockchain_tx": "0x..."
}

certification.revoked

Fired when a certification is revoked.

When: Verification no longer valid or content modified

Payload:

{
  "event_type": "certification.revoked",
  "timestamp": "2024-01-15T11:30:00Z",
  "organization_id": "org-abc123",
  "certification_id": "cert-abc123",
  "revocation_reason": "content_modified",
  "revoked_by": "admin@company.com",
  "revocation_notes": "Source content changed significantly",
  "issued_at": "2024-01-01T00:00:00Z"
}

certification.expiring

Fired when certification is approaching expiration.

When: 7 days before expiration (configurable)

Payload:

{
  "event_type": "certification.expiring",
  "timestamp": "2024-01-08T00:00:00Z",
  "organization_id": "org-abc123",
  "certification_id": "cert-abc123",
  "days_until_expiration": 7,
  "expires_at": "2024-01-15T11:00:00Z",
  "renewal_url": "https://truthvouch.io/renew/cert-abc123"
}

Compliance Events

compliance.scan_completed

Fired when a compliance scan finishes.

When: Background scan completes

Payload:

{
  "event_type": "compliance.scan_completed",
  "timestamp": "2024-01-15T12:00:00Z",
  "organization_id": "org-abc123",
  "scan_id": "scan-abc123",
  "scan_type": "gdpr",
  "status": "completed",
  "results": {
    "total_items_scanned": 1500,
    "violations_found": 23,
    "critical": 3,
    "high": 8,
    "medium": 12,
    "compliance_score": 0.82
  },
  "report_url": "https://dashboard.truthvouch.io/reports/scan-abc123"
}

compliance.violation_detected

Fired when a compliance violation is detected.

When: During compliance scan

Payload:

{
  "event_type": "compliance.violation_detected",
  "timestamp": "2024-01-15T12:05:00Z",
  "organization_id": "org-abc123",
  "violation_id": "viol-xyz789",
  "regulation": "gdpr",
  "violation_type": "unauthorized_processing",
  "severity": "high",
  "affected_resources": {
    "user_count": 45,
    "data_items": 120
  },
  "remediation_steps": [
    "Review user consent records",
    "Document legal basis for processing",
    "Update privacy policy"
  ]
}

compliance.report_generated

Fired when compliance report is generated.

When: On schedule or on-demand

Payload:

{
  "event_type": "compliance.report_generated",
  "timestamp": "2024-01-15T13:00:00Z",
  "organization_id": "org-abc123",
  "report_id": "report-abc123",
  "report_type": "soc2",
  "period": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-15"
  },
  "status": "available",
  "download_url": "https://dashboard.truthvouch.io/reports/report-abc123/download",
  "expiration_date": "2024-02-15"
}

Monitoring Events

sentinel.online

Fired when Sentinel agent comes online.

When: Agent connects to cloud

Payload:

{
  "event_type": "sentinel.online",
  "timestamp": "2024-01-15T08:00:00Z",
  "organization_id": "org-abc123",
  "agent_id": "agent-abc123",
  "device_name": "CORP-LAP-001",
  "os": "windows",
  "os_version": "11",
  "agent_version": "1.5.2",
  "ip_address": "203.0.113.100"
}

sentinel.offline

Fired when Sentinel agent goes offline.

When: Agent loses connection for >5 minutes (configurable)

Payload:

{
  "event_type": "sentinel.offline",
  "timestamp": "2024-01-15T08:30:00Z",
  "organization_id": "org-abc123",
  "agent_id": "agent-abc123",
  "device_name": "CORP-LAP-001",
  "offline_since": "2024-01-15T08:30:00Z",
  "last_heartbeat": "2024-01-15T08:29:55Z",
  "reason": "network_timeout"
}

sentinel.policy_sync_failed

Fired when Sentinel fails to sync policies.

When: Sync attempt fails after retries

Payload:

{
  "event_type": "sentinel.policy_sync_failed",
  "timestamp": "2024-01-15T09:00:00Z",
  "organization_id": "org-abc123",
  "agent_id": "agent-abc123",
  "device_name": "CORP-LAP-001",
  "error": "connection_timeout",
  "error_details": "Failed to reach policy endpoint after 5 retries",
  "last_successful_sync": "2024-01-15T08:00:00Z",
  "policies_stale_since": "1 hour"
}

sentinel.threat_detected

Fired when Sentinel detects a threat locally.

When: Policy violation or suspicious behavior

Payload:

{
  "event_type": "sentinel.threat_detected",
  "timestamp": "2024-01-15T09:15:00Z",
  "organization_id": "org-abc123",
  "agent_id": "agent-abc123",
  "device_name": "CORP-LAP-001",
  "threat_type": "pii_exposure_attempt",
  "threat_level": "high",
  "details": {
    "tool_name": "ChatGPT",
    "user": "john.doe",
    "pii_type": "credit_card",
    "action_taken": "blocked",
    "timestamp": "2024-01-15T09:15:00Z"
  },
  "remediation_required": true
}

Governance Events

policy.updated

Fired when a governance policy is updated.

When: Administrator saves policy changes

Payload:

{
  "event_type": "policy.updated",
  "timestamp": "2024-01-15T14:00:00Z",
  "organization_id": "org-abc123",
  "policy_id": "policy-abc123",
  "policy_name": "AI Tool Allowlist",
  "version": "v2.1",
  "changed_by": "admin@company.com",
  "changes": {
    "added_tools": ["claude-3"],
    "removed_tools": ["gemini-free"],
    "modified_rules": ["pii_detection_threshold"]
  },
  "rollout_strategy": "gradual",
  "rollout_percentage": 50,
  "affected_agents": 250
}

policy.deployment_status

Fired when policy deployment status changes.

When: Agents check in with new/old policy versions

Payload:

{
  "event_type": "policy.deployment_status",
  "timestamp": "2024-01-15T14:30:00Z",
  "organization_id": "org-abc123",
  "policy_id": "policy-abc123",
  "deployment_status": "in_progress",
  "summary": {
    "total_agents": 500,
    "deployed": 250,
    "pending": 200,
    "failed": 50
  },
  "completion_percentage": 50,
  "estimated_completion": "2024-01-15T15:30:00Z"
}

Retry Behavior

Events are retried automatically:

  • Attempt 1: Immediate
  • Attempt 2: 1 minute delay
  • Attempt 3: 5 minutes delay
  • Attempt 4: 30 minutes delay
  • Attempt 5: 2 hours delay
  • Final: 12 hours delay

After max retries, events are sent to dead letter queue.

Testing Events

Send Test Event

Dashboard:

  1. Settings → Webhooks
  2. Select webhook
  3. Click “Send Test Event”
  4. Choose event type
  5. Review payload and send

API:

Terminal window
curl -X POST https://api.truthvouch.io/v1/webhooks/test \
  -H "Authorization: Bearer token" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_id": "wh-abc123",
    "event_type": "alert.detected"
  }'

Event Filtering

Subscribe to specific events:

{
  "url": "https://yourserver.com/webhooks",
  "events": [
    "alert.detected",
    "alert.resolved",
    "compliance.scan_completed"
  ],
  "active": true
}

See Webhooks Index, Signature Verification, and Retries for implementation details.