> Source: https://vitna.ai/docs/api/v1/engine/org-webhooks
> Raw Markdown: https://vitna.ai/docs/api/v1/engine/org-webhooks.md
> Corpus index: https://vitna.ai/llms.txt
# 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}/disable
```
```
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."
}
}
```