# Detection Webhooks

`com.glidevizion.detection-webhooks` forwards durable detection cards to a
user-owned HTTP or HTTPS endpoint. It consumes saved Hikvision smart events and
local-model findings rather than raw motion edges, so downstream alerts can be
filtered by label and confidence.

The extension requests only:

- `detections:read` for scoped metadata and evidence JPEGs;
- `network:outbound` for the configured webhook;
- `ui:settings.panel` for its reviewed settings form.

It cannot read camera credentials, RTSP streams, recording files, or raw motion
events. Grant one camera under **Camera access**, then choose that same camera in
settings.

## Delivery contract

Each matching detection is sent as JSON with a stable delivery ID:

```json
{
  "plugin_id": "com.glidevizion.detection-webhooks",
  "camera_id": "cam01",
  "delivery_id": "cam01:detection:42",
  "detection": {
    "id": "42",
    "time_ms": 1784052000000,
    "playback_ms": 1784051998500,
    "event_type": "person",
    "label": "person",
    "confidence": 0.94,
    "source": "plugin:com.glidevizion.coreml-detector"
  },
  "evidence_jpeg_base64": "...optional..."
}
```

The same ID is sent in `X-NVR-Delivery-ID`. When a shared secret is configured,
`X-NVR-Signature` is `sha256=<hex HMAC-SHA256 of the exact request body>`.
Delivery is at least once: receivers must deduplicate by delivery ID. The worker
checkpoints every processed `(time_ms, id)` under `NVR_PLUGIN_STATE_DIR`, so
filters, restarts, and timestamp ties do not replay or skip later detections.

Evidence images are disabled by default. Enabling them attaches the immutable
JPEG already owned by the selected detection; the worker rejects cross-camera
or absolute evidence URLs and caps the image at 8 MiB.

## Local development

```bash
go build -o detection-webhooks ./plugins/detection-webhooks/cmd/detection-webhooks

NVR_BASE_URL=http://127.0.0.1:8085 \
NVR_API_TOKEN=dev-token \
NVR_PLUGIN_STATE_DIR=/tmp/nvr-detection-webhooks \
WEBHOOK_URL=https://example.com/nvr/detections \
CAMERA_ID=cam01 \
MINIMUM_CONFIDENCE=0.5 \
LABELS=person,vehicle \
./detection-webhooks
```
