Hooks

Hooks let you extend Veriva without forking. Two hook types ship today: sandboxed shell commands and outbound webhooks. Hooks are configured per-org from Settings → Hooks, or in-repo at .veriva/rules/*.yml. In-repo wins on conflict.

Shell hooks

Sandboxed shell command. Runs in a Docker container with no network and a 30s timeout. Output is parsed for findings — write to stdout in our JSON format or wrap an existing tool.

# .veriva/rules/license-headers.yml
	type: shell
	script: |
	  ./scripts/check-license-headers.sh \
	    "$CHANGED_FILES_JSON" \
	    --format=veriva-json

Available env vars in the sandbox: CHANGED_FILES_JSON, HEAD_SHA, BASE_SHA, PR_ID, and PR_NUMBER.

Webhook hooks

POST to your URL with PR context. Expect a findings JSON response within 5 seconds. Useful for integrating with internal tooling — your own static analyzer, a license server, an internal threat-intel API.

# .veriva/rules/internal-threat-intel.yml
type: webhook
url: https://threat-intel.example.com/veriva/check
events: ["pr_opened", "pr_synchronized"]
timeout: 5000

Outbound requests are signed with HMAC-SHA256 over the body. The signing secret is shown once when you create the hook — store it on your end and verify the X-Veriva-Signature header on every request.

Replay protection: requests carry a X-Veriva-Timestamp header; reject anything older than 5 minutes.

See API reference → webhook hooks for the full payload schema, signing-key rotation, and the expected response format.

Deferred hook types

Rule and LLM hooks are not creatable today. They remain in the database enum for historical rows and forward compatibility, but new hook creation is restricted to shell and webhook until customers pull those executors into the product.

Precedence

1. In-repo hooks at .veriva/rules/*.yml at the PR head SHA
2. Per-repo hooks configured in the dashboard
3. Org-level hooks configured in the dashboard

Within a tier, more specific matches win. A rule with both paths and agentType set beats a rule with only paths set.