Webhooks

How It Works

Webhooks let you receive automatic notifications when events occur in Veridox, such as a file analysis completing.

Create a webhook configuration

Someone with organisation_settings:write creates a webhook configuration, providing a destination URL where you want to receive events.

Store your signing secret

Veridox provisions a signing secret (format: whsec_{32-char-alphanumeric}) and returns it once in the creation response. After that, only a prefix is shown for identification.

The secret is only shown once at creation time. Store it securely; you cannot retrieve it again.

Receive events

When events occur, Veridox sends a POST request to your URL with:

A JSON payload in the body
An x-vdx-timestamp header holding the time the request was sent, in Unix seconds
An x-vdx-signature header containing an HMAC-SHA256 hex digest, signed with your webhook secret over the timestamp and the body; see Signature Verification

Verify and process

You verify the signature and the timestamp on your server to confirm the request genuinely came from Veridox, hasn’t been tampered with, and isn’t an old request being replayed, then process the event.

Event Types

Event type	Description
`file.enrichment.success`	File analysis completed successfully

Analysis failures are not currently delivered to configured webhook endpoints. To detect a file that did not complete, poll the file’s analysis_status via List Files or subscribe to case progress.

Every payload carries an event_type. Branch on it rather than assuming a single shape, so that new event types added later do not break your receiver.

Delivery Semantics

Behaviour	Detail
Success criteria	Any `2xx` response. Your endpoint has 30 seconds to respond.
Retries	Up to 48 attempts at fixed 30-minute intervals, covering roughly 24 hours. Any non-`2xx` response, timeout, or connection error triggers the next attempt.
After retries	Delivery stops. Contact support with the `trace_id` if you need an event resent.
Ordering	Not guaranteed. Files within a case complete independently and may arrive in any order.
Duplicates	Possible. A retry after your endpoint accepted the request but failed to respond in time will redeliver the same event.

A 2xx is terminal. It stops all further retries for that event. Send one only once you have taken responsibility for the event, because nothing will redeliver it afterwards.

Use event_id to recognise a repeat delivery. It is the same on every retry of an event. trace_id identifies the analysis rather than the delivery, and completed_at is not unique.

Responding

Keep your response inside the 30-second window and hand the event to your own code for anything slower. What matters is only this:

Return 2xx once you have taken responsibility for the event. This stops redelivery.
Return any non-2xx, or nothing at all, if you could not accept it. This asks for a retry, and you have roughly 24 hours of them.

Because a non-2xx simply schedules the next attempt, returning an error while you are unavailable is safe. The same event comes back every 30 minutes until you accept it.

Payload Structure

The example below is abridged; arrays are truncated and some sections are collapsed. See the Webhook Payload Reference for every key, its type and an example value.

{
  "event_type": "file.enrichment.success",
  "event_id": "enrichment_01a039f1-1e01-7b0b-a952-4e6d907ab221_01a039f1-1e46-79ee-a5c1-fc653b9f:file.enrichment.success",
  "case_id": "01a039f1-1e01-7b0b-a952-4e6d907ab221",
  "file_id": "01a039f1-1e46-79ee-a5c1-fc653b9f8f64",
  "trace_id": "enrichment_01a039f1-1e01-7b0b-a952-4e6d907ab221_01a039f1-1e46-79ee-a5c1-fc653b9f",
  "started_at": "2026-08-25T17:21:40.912430+00:00",
  "completed_at": "2026-08-25T17:23:21.342763+00:00",
  "blob_name": "documents/01a039f1-1e01-7b0b-a952-4e6d907ab221/01a039f1-1e46-79ee-a5c1-fc653b9f8f64",
  "version": "2",
  "file_info": {
    "mimetype": "image/jpeg",
    "md5": "82cc5e174bf6fb87dfd87e98ab965120",
    "raw_metadata": {
      "file_size": 70059,
      "image_format": "JPEG",
      "image_width": 544,
      "image_height": 768,
      "metadata": { "success": true, "tags_count": 10, "tags": { "Image Mode": "RGB" }, "message": "..." }
    }
  },
  "ocr_summary": "This is a photograph of a paper utility bill payment advice page...",
  "results": {
    "summary": "This document is a photograph of a utility bill payment slip dated November 7, 2023...",
    "overall_risk_score": "Informational",
    "findings": [
      {
        "heading": "Metadata Stripped",
        "category": "Manipulation & Forgery Detection",
        "description": "The file is classified as a photograph of a document but lacks camera EXIF metadata.",
        "supporting_evidence": ["Image Metadata: tags_count: 10, containing only basic JFIF info tags"],
        "source_analysis": "manipulation_detection",
        "alert_type": "METADATA_STRIPPED",
        "custom_alert_type": null,
        "severity": "Informational",
        "severity_justification": "Classified as Informational for missing camera metadata on photograph documents."
      }
    ],
    "suggested_actions": [{ "action": "Verify VAT status manually", "justification": "The automated check was unavailable." }],
    "observations": ["File Category: Photo of Document (PHOTO_OF_DOCUMENT) classified as a Utility Bill."],
    "audit_trail": ["Error Level Analysis (ELA): Measured pixel compression variance."],
    "modules_run": ["content_verification", "manipulation_detection", "barcode_analysis", "ela_fraud_detection"],
    "search_evidence_summary": { "total_queries": 0, "total_results": 0, "per_module": {} },
    "verification_evidence_summary": {
      "total_checks": 4,
      "resolved": 3,
      "failed": 1,
      "per_module": { "content_verification": { "checks": ["..."] } }
    },
    "case_context_at_analysis": null
  },
  "modules": [
    {
      "module_id": "content_verification",
      "module_name": "Content Verification",
      "findings": [
        {
          "alert_type": "IDENTIFIER_NOT_VERIFIED",
          "alert_type_name": "Identifier Not Verified",
          "found": false,
          "custom_alert_type": null,
          "severity": "Informational",
          "severity_justification": "",
          "description": "All checked identifiers were valid or returned inconclusive results without contradiction.",
          "evidence": [],
          "evidence_refs": []
        }
      ],
      "error": null,
      "search_evidence": { "queries": [], "results": [], "failures": [], "elapsed_ms": 4678, "request_count": 0 },
      "verification_evidence": {
        "checks": [
          {
            "check_id": "v1",
            "provider": "companies_house",
            "check_type": "company",
            "subject": "03078711",
            "subject_date": null,
            "country_code": "GB",
            "is_valid": true,
            "canonical_name": "BRITISH GAS TRADING LIMITED",
            "canonical_address": null,
            "checked_at": "2026-08-25T17:22:22.132531+00:00",
            "extracted": "03078711",
            "outputs": { "company_status": "active", "postcode": "SL4 5GD", "type": "ltd" },
            "attests": "Company registered per Companies House (live status + registered address)",
            "country_mismatch": false,
            "error": null
          }
        ]
      }
    }
  ],
  "analysis_metadata": {
    "ela": { "mean_diff": 0.184, "std_diff": 0.779, "percent_anomaly": 4.277, "image_path": "ela/...", "was_scaled": false, "scaling_info": null },
    "reverse_search": { "matches": null, "total": 0, "external_services": ["..."], "error": null },
    "thumbnail": { "path": "thumbs/...", "format": "JPEG", "dimensions": { "width": 106, "height": 150 }, "size_bytes": 4227, "quality": 80 },
    "barcode_results": [{ "type": "QR Code", "symbology": "QRCode", "value": "...", "status": "HANDLED", "fields": { "content_type": "Text" }, "info": "..." }],
    "ocr": { "file_category": "PHOTO_OF_DOCUMENT", "extracted_details": { "...": "..." }, "classifications": ["..."], "contains_embedded_images": false },
    "pdf_structure": null,
    "annotations": null
  },
  "artifacts": {
    "report_pdf": "reports/01a039f1-.../01a039f1-....pdf",
    "report_log": "logs/output-enrichment_01a039f1-....txt",
    "thumbnail": "thumbs/01a039f1-.../01a039f1-....jpg",
    "ela_overlay": "ela/01a039f1-.../01a039f1-....ela.jpg",
    "annotated_pdf": null
  },
  "integrity_signals": {
    "reasoning": "No evidence of image manipulation, tampering, or inconsistency was found.",
    "image_manipulated": false,
    "content_edited": false,
    "metadata_manipulated": false,
    "ai_generated": false,
    "ai_edited": false,
    "reuse_online": false,
    "risk_category": "Low"
  },
  "highlights": ["The document is a legitimate utility bill with a total balance of GBP 338.41."],
  "caveats": [
    {
      "type": "external_service_failed",
      "severity": "warn",
      "title": "Verification could not be completed",
      "message": "The authoritative source could not be reached; this check is unverified. Absence of confirmation is not evidence of a problem.",
      "scope": "document",
      "scope_ref": "v2",
      "affected_modules": ["content_verification"],
      "affected_findings": null
    }
  ]
}

Absent keys versus null

Handling these two cases wrongly is the most common integration bug:

Optional top-level sections may be absent, or present with the value null. This applies to results, integrity_signals, highlights, ocr_summary, and trace_id. Treat both forms identically and use a null-safe accessor.
Nested keys are always present, carrying null where a step did not apply to the file. Everything inside analysis_metadata, artifacts, file_info, and each module follows this rule.
caveats and modules are always arrays, never null.
previously_seen_at is absent rather than null when previously_seen is false.

Do not rely on which form you receive for an optional section. Checking only "results" in payload, or only payload.results !== null, will break on the other form. In TypeScript prefer payload.results?.overall_risk_score; in Python prefer (payload.get("results") or {}).

Do not index into modules or findings by position. Which modules run depends on the file type and your organisation’s enabled modules, so both the length and the ordering vary between analyses. Look modules up by module_id, and findings by alert_type.

Field notes

Field	Note
`version`	The string `"2"`. It is a payload schema version, not a semantic version; compare it exactly.
`previously_seen`	`true` when the file repeats one already uploaded in your organisation and its earlier analysis was reused. The payload then carries no analysis of its own; see the payload reference.
`started_at`, `completed_at`	ISO 8601 with a UTC offset and microsecond precision, for example `2026-08-25T17:21:40.912430+00:00`. Not the `Z` suffix form.
`overall_risk_score`, `severity`	Title-case: `Informational`, `Low`, `Medium`, `High`.
`highlights`	Top-level, not inside `results`. Present only when the Analysis Highlights module is enabled for your organisation.
`artifacts.*`	Storage paths, not URLs. Exchange them for short-lived signed URLs via Get Asset URL.
`blob_name`	An internal reference to the stored file. It cannot be fetched; use `file_id` with Get Asset URL to retrieve the original.
Unrecognised keys	Some keys exist for Veridox diagnostics and are not part of the published contract. Ignore anything not listed in the payload reference.
`modules[].findings`	Contains one entry per check the module ran, including those that did not fire. Filter on `found === true`.
`results.findings`	Only the findings that fired, summarised for analysts.

Module Evidence

Each entry in modules carries its findings alongside the evidence that supports them:

Field	Type	Description
`findings`	array	One entry per alert type the module checks. Each has an `alert_type`, a `found` boolean, a `severity` (`Informational`, `Low`, `Medium`, or `High`), a `description`, a `severity_justification`, an `evidence` list, and `evidence_refs`.
`search_evidence`	object \| null	Audit trail of the grounded research run for this module: the `queries`, their `results`, any `failures`, and timing. `null` when the module performed no search.
`verification_evidence`	object \| null	Deterministic checks against authoritative registries and APIs, such as company registries, tax registers, and address validation. `null` when the module ran no such checks. Checks run only when your organisation’s verification setting is on for the analysis.

The two carry different weight and are kept separate for that reason. search_evidence is web research with a synthesised answer, so it is corroborative. verification_evidence is a direct check against an authoritative source, so it is definitive. Show them distinctly to your reviewers rather than combining them into one evidence list.

In a verification check, is_valid: null means “could not be verified”, not “invalid”. It usually means the authoritative source was unreachable or does not cover the subject, and a matching entry in caveats will normally say so. Presenting it as a negative result will mislead your reviewers.

A finding’s evidence_refs are IDs that point back into its module’s evidence, so you can resolve each claim to its source:

IDs like q1.1 resolve against search_evidence.results, matched on result_id. The trailing index is 1-based and matches the [1] citation markers in the query’s answer.
IDs like v1 resolve against verification_evidence.checks, matched on check_id.

The results.search_evidence_summary and results.verification_evidence_summary objects roll the same evidence up across modules, keyed by module_id, which is useful for rendering an overview without walking every module.

Both summary objects may be null, and a query’s answer may be null. Treat them as optional when parsing.

Analysis Caveats

The caveats array records limits on how far an analysis should be trusted, such as an authoritative source being unreachable or text recognition quality being poor. Each caveat carries a severity of info, warn, or critical. A critical caveat on an otherwise clean analysis is the case worth surfacing to your reviewers: it means the clean verdict itself is not dependable. See caveats for every field.

Signature Verification

The x-vdx-signature header is computed as:

HMAC-SHA256(x_vdx_timestamp + "." + raw_request_body, your_webhook_secret) -> hex string

To verify a request:

Read the x-vdx-timestamp header and reject the request if it is more than five minutes away from your current time.
Compute the HMAC over the timestamp, a ., and the raw request bytes.
Compare it against the x-vdx-signature header using a timing-safe comparison.

Every delivery attempt, including each retry, is signed with a fresh timestamp, so a legitimate retry always passes the five-minute check. A request captured and sent again later fails it. Within the five-minute window, use event_id to recognise a repeat.

Sign the raw request bytes, exactly as received. Parsing the JSON and re-serialising it changes the bytes (key order, whitespace, unicode escaping) and the signature will not match. Configure your framework to give you the raw body on this route: express.raw() in Express, or disable body parsing for the webhook path.

Signature scheme change

Previously, x-vdx-signature was an HMAC over the raw body alone, which does not protect against a replayed request. It now uses the timestamped form above. The samples below accept either form while ACCEPT_BODY_ONLY_SIGNATURE is on, which let you change over without missing a webhook. Turn ACCEPT_BODY_ONLY_SIGNATURE off: leaving it on keeps accepting old requests that were captured before the switch, which is exactly what the timestamp exists to prevent. A receiver that still verifies the body-only form alone will reject webhooks.

Node.js
Python

import { createHmac, timingSafeEqual } from "node:crypto";
import { createServer } from "node:http";

const WEBHOOK_SECRET = "whsec_your_secret_here";
const TOLERANCE_SECONDS = 300;
// Turn off once the signature scheme switch has happened.
const ACCEPT_BODY_ONLY_SIGNATURE = true;

function matches(signature, ...parts) {
  const hmac = createHmac("sha256", WEBHOOK_SECRET);
  for (const part of parts) hmac.update(part);
  const given = Buffer.from(signature, "utf8");
  const want = Buffer.from(hmac.digest("hex"), "utf8");
  return given.length === want.length && timingSafeEqual(given, want);
}

function verifySignature(rawBody, timestamp, signature) {
  if (!signature) return false;
  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
  if (timestamp && age <= TOLERANCE_SECONDS && matches(signature, `${timestamp}.`, rawBody)) return true;
  return ACCEPT_BODY_ONLY_SIGNATURE && matches(signature, rawBody);
}

createServer(async (req, res) => {
  const chunks = [];
  for await (const chunk of req) chunks.push(chunk);
  const rawBody = Buffer.concat(chunks);

  if (!verifySignature(rawBody, req.headers["x-vdx-timestamp"], req.headers["x-vdx-signature"])) {
    res.writeHead(401).end();
    return;
  }

  const event = JSON.parse(rawBody.toString("utf8"));

  try {
    // Your code. Anything slow belongs outside this handler.
    await acceptEvent(event);
  } catch {
    res.writeHead(503).end(); // ask for a retry
    return;
  }

  res.writeHead(200).end();
}).listen(3000);

import hashlib
import hmac
import json
import time
from http.server import BaseHTTPRequestHandler, HTTPServer

WEBHOOK_SECRET = "whsec_your_secret_here"
TOLERANCE_SECONDS = 300
# Turn off once the signature scheme switch has happened.
ACCEPT_BODY_ONLY_SIGNATURE = True


def matches(signature: str, message: bytes) -> bool:
    expected = hmac.new(WEBHOOK_SECRET.encode(), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)


def verify_signature(raw_body: bytes, timestamp: str, signature: str) -> bool:
    fresh = timestamp.isascii() and timestamp.isdigit() and abs(time.time() - int(timestamp)) <= TOLERANCE_SECONDS
    if fresh and matches(signature, timestamp.encode() + b"." + raw_body):
        return True
    return ACCEPT_BODY_ONLY_SIGNATURE and matches(signature, raw_body)


class WebhookHandler(BaseHTTPRequestHandler):
    def do_POST(self):
        length = int(self.headers.get("Content-Length", 0))
        raw_body = self.rfile.read(length)
        timestamp = self.headers.get("x-vdx-timestamp", "")
        signature = self.headers.get("x-vdx-signature", "")

        if not verify_signature(raw_body, timestamp, signature):
            self.send_response(401)
            self.end_headers()
            return

        event = json.loads(raw_body)

        try:
            # Your code. Anything slow belongs outside this handler.
            accept_event(event)
        except Exception:
            self.send_response(503)  # ask for a retry
            self.end_headers()
            return

        self.send_response(200)
        self.end_headers()


HTTPServer(("", 3000), WebhookHandler).serve_forever()

Best Practices

Store secrets securely because the signing secret is shown once at creation time and cannot be retrieved again

Always verify signatures against the raw request bytes before doing anything with the payload

Reject stale requests whose x-vdx-timestamp is more than five minutes from your current time

Use timing-safe comparison to prevent timing attacks

Respond within 30 seconds, and do slower work outside the request

Recognise repeat deliveries using event_id, which is the same on every retry of an event

Ignore keys you do not recognise so that keys added later do not break your receiver

Only one active webhook configuration is allowed per organisation at a time. Creating a new configuration deactivates the previous one.

Getting Started

Core Features

Resources

How It Works

Event Types

Delivery Semantics

Responding

Payload Structure

Absent keys versus null

Field notes

Module Evidence

Analysis Caveats

Signature Verification

Signature scheme change

Best Practices

​How It Works

​Event Types

​Delivery Semantics

​Responding

​Payload Structure

​Absent keys versus null

​Field notes

​Module Evidence

​Analysis Caveats

​Signature Verification

​Signature scheme change

​Best Practices

How It Works

Event Types

Delivery Semantics

Responding

Payload Structure

Absent keys versus null

Field notes

Module Evidence

Analysis Caveats

Signature Verification

Signature scheme change

Best Practices