Get started

Policy drift webhooks

Source

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.

text
GET /api/v1/org/webhooks
POST /api/v1/org/webhooks
POST /api/v1/org/webhooks/{id}/test
POST /api/v1/org/webhooks/{id}/disable
text
Authorization: Bearer vitna_push_...
bash
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

json
{
  "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."
  }
}