Skip to content
VeraFrame Docs

Webhooks

Webhooks let VeraFrame push validation events to your other systems as soon as they happen. Instead of polling the API to find out when a generation finished, your ticketing system, AI governance platform, or CRM can receive a POST the moment the trust report is ready.

Webhooks are available on Integration deployments. Each tenant can configure one webhook endpoint.

The event

The primary event emitted is:

veraframe.validation.findings

It fires once per completed validation (across all modes: Generate, Audit, Ask, JSON API).

Payload shape

{
  "event_type": "veraframe.validation.findings",
  "timestamp": 1776262925,
  "customer_id": "your-tenant-id",
  "customer_name": "Your Company",
  "validation_id": "val_xyz789",
  "mode": "generate",
  "question": "Summarize the current SLA terms",
  "severity": "medium",
  "confidence_level": "MEDIUM",
  "issue_count": 3,
  "issues": ["Some claims require review"],
  "findings": [
    {
      "category": "source_validation",
      "status": "mismatch",
      "title": "Response time",
      "description": "Claim does not match the source value",
      "severity": "high"
    }
  ],
  "user_corrections": [
    {
      "element": "response_time",
      "action": "override",
      "note": "Use the updated contract addendum"
    }
  ],
  "source_conflict_count": 1,
  "output_excerpt": "...",
  "user": {
    "user_id": "user_123",
    "name": "Example User",
    "role": "admin"
  }
}

The exact payload is defined by the deployed webhook dispatcher. The fields above reflect the current implementation.

Configuration

Webhooks are configured per-tenant:

  • webhook.enabled — boolean, defaults to false.
  • webhook.url — your endpoint URL.
  • webhook.bearer_token — optional bearer token VeraFrame sends in the Authorization header.
  • webhook.include_successful — by default, webhooks are only sent for validations with at least one issue. Set this to true to receive every validation, even clean ones.

For SaaS Cloud, webhook configuration is not exposed in the UI. For Integration deployments, it is part of the tenant configuration file managed by the operations team.

Delivery semantics

  • Fire-and-forget. VeraFrame sends the POST and does not wait for a slow receiver.
  • 5-second timeout. If your endpoint does not respond within 5 seconds, the delivery is considered failed. VeraFrame logs the failure but does not block the validation from being returned to the user.
  • No automatic retry. A failed webhook is not retried automatically. This is deliberate: webhooks are a notification channel, not the system of record. The authoritative data is always available via the REST API.
  • Best-effort ordering. Events are generally in chronological order but should not be strictly required to be — consumers should use the timestamp and event_id fields to reconcile.

Verifying the sender

If you configure a bearer_token, VeraFrame sends it in every webhook request as:

Authorization: Bearer <your-token>

Your receiving endpoint should verify this token before processing the payload. This is a shared-secret model; rotate the token periodically like any other credential.

Typical uses

  • Ticketing integration. Every validation with a red finding opens a ticket in Jira, ServiceNow, or an internal system.
  • Data quality feedback. Findings that indicate a source conflict are routed to the team that owns the underlying source data.
  • Chatbot improvement loop. When Chatbot Audit mode flags a response, the finding becomes training data for the chatbot team.
  • Governance tooling. Validations requiring external review are pushed to your governance platform via webhook and reflected back through the external review API.

Not a replacement for polling

Webhooks are a notification channel, not a queue. If your receiver is down during delivery, that event is lost from the webhook stream. For downstream processes that must not miss events, poll POST /api/v1/history or POST /api/v1/audit on a schedule and treat webhooks as a low-latency hint that new data is available.