Policy drift webhooks
Register, test and soft-disable HMAC-SHA256 signed webhook endpoints for policy drift, newly signed policy bundles and fired price watches on Deploy and agreement organisations.
GET /api/v1/org/webhooks
POST /api/v1/org/webhooks
POST /api/v1/org/webhooks/{id}/test
POST /api/v1/org/webhooks/{id}/disableAuthorization: Bearer vitna_push_...curl -X POST https://vitna.ai/api/v1/org/webhooks \
-H "authorization: Bearer vitna_push_..." \
-H "content-type: application/json" \
-d '{
"url": "https://ops.example.com/webhooks/vitna",
"events": ["policy.drift_detected", "policy.bundle_signed"],
"description": "Production CI drift receiver"
}'Entitlement and SSRF safety
Registering and testing webhooks require Deploy ($79 a month) or recorded agreement terms; metered organisations on the free allowance receive 402 plan_upgrade_required pointing to /console/billing.
Destination URLs must use https:// on a public internet hostname. Loopback, localhost, RFC1918 private networks, link-local metadata addresses and .local/.internal suffixes are refused at registration and before delivery.
Signature verification
At registration signingSecret (whsec_vitna_...) is returned once and sealed at rest with AES-256-GCM under VITNA_CONNECTION_KEY. Subsequent GET /api/v1/org/webhooks listings expose only secretFingerprint (sha256 hex).
Every delivery serialises its JSON body with deterministic lexicographic key ordering and signs the exact UTF-8 wire bytes with HMAC-SHA256 in x-vitna-signature-256: sha256=<hex>, alongside x-vitna-event and x-vitna-delivery.
Registration response
{
"data": {
"id": 4,
"orgId": "convexity",
"workloadId": null,
"url": "https://ops.example.com/webhooks/vitna",
"description": "Production CI drift receiver",
"events": ["policy.drift_detected", "policy.bundle_signed"],
"secretFingerprint": "5a91e8c4b0f1a2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7",
"status": "active",
"createdAt": "2026-09-14T12:00:00.000Z",
"disabledAt": null,
"disabledReason": null,
"signingSecret": "whsec_vitna_example_shown_once"
},
"meta": {
"generatedAt": "2026-09-14T12:00:00.000Z",
"orgId": "convexity",
"signatureHeader": "x-vitna-signature-256",
"note": "signingSecret is returned once at registration. Store it in your receiver and verify x-vitna-signature-256 over the raw request body."
}
}