NVR HTTP POST Webhook API – AI Detection Events

Home > CCTV Security Camera & Video Surveillance System Forums > Viewtron Security Camera Systems > IP Camera API > NVR HTTP POST Webhook API – AI Detection Events

Viewing 1 post (of 1 total)
  • Author
    Posts
  • February 26, 2026 at 2:53 pm #42568
    Mike Haldas
    Keymaster

    API Webhooks for NVR AI Detection Events

    Viewtron NVRs can forward AI detection events from connected cameras to your custom server via HTTP Post webhooks. This reference documents the NVR API format (v2.0) and supported detection types.

    Looking for IP Camera API? If your cameras connect directly to your network (not through an NVR’s PoE ports), see API Webhooks for AI Security Camera Alarms instead.

    Setup Instructions: See How to Setup NVR API Webhook Events for configuration steps.

    NVR vs IP Camera API Format

    The NVR uses API version 2.0, which has a different XML structure than the IP Camera v1.x format:

    Feature IP Camera (v1.x) NVR (v2.0)
    Detection type codes Abbreviated (PEA, VFD, VEHICE) Spelled out (regionIntrusion, lineCrossing)
    Timestamp Unix seconds/milliseconds Unix microseconds (16 digits)
    Device info fields ipAddress, macAddress ip, mac, channelId
    Message types None keepalive, alarmStatus, alarmData
    Target images listInfo targetListInfo
    Target type Numeric (1=person, 2=car) String (person, car)
    Good news for developers: Our Python API server on GitHub handles both formats automatically. The same code processes IP Camera and NVR webhooks – you don’t need to handle the differences yourself.

    Message Types

    The NVR sends three types of HTTP Posts:

    Keepalive

    Periodic heartbeat (no event data).

    <?xml version="1.0" encoding="UTF-8"?>
<config version="2.0.0" xmlns="http://www.ipc.com/ver10">
    <messageType>keepalive</messageType>
    <deviceInfo>
        <deviceName><![CDATA[NVR Name]]></deviceName>
        <ip><![CDATA[192.168.0.55]]></ip>
        <mac><![CDATA[58:5B:69:40:F4:0D]]></mac>
    </deviceInfo>
</config>

    Alarm Status

    Lightweight notification when an alarm triggers or clears (no images).

    <?xml version="1.0" encoding="UTF-8"?>
<config version="2.0.0" xmlns="http://www.ipc.com/ver10">
    <messageType>alarmStatus</messageType>
    <deviceInfo>
        <deviceName><![CDATA[NVR Name]]></deviceName>
        <ip><![CDATA[192.168.0.55]]></ip>
        <mac><![CDATA[58:5B:69:40:F4:0D]]></mac>
        <channelId>1</channelId>
    </deviceInfo>
    <currentTime>1772056914000000</currentTime>
    <alarmStatusInfo>
        <perimeterAlarm><item id="1">true</item></perimeterAlarm>
    </alarmStatusInfo>
</config>

    Alarm Data

    Full event with detection details and images.

    <?xml version="1.0" encoding="UTF-8"?>
<config version="2.0.0" xmlns="http://www.ipc.com/ver10">
    <messageType>alarmData</messageType>
    <deviceInfo>
        <deviceName><![CDATA[NVR Name]]></deviceName>
        <ip><![CDATA[192.168.0.55]]></ip>
        <mac><![CDATA[58:5B:69:40:F4:0D]]></mac>
        <channelId>1</channelId>
    </deviceInfo>
    <smartType>regionIntrusion</smartType>
    <currentTime>1772056914604000</currentTime>
    <eventInfo>
        <item>
            <eventId>916</eventId>
            <targetId>716</targetId>
            <boundary>area</boundary>
            <pointGroup>
                <item><x>1590</x><y>3080</y></item>
                <item><x>4715</x><y>3181</y></item>
                <item><x>4772</x><y>9217</y></item>
                <item><x>416</x><y>9141</y></item>
            </pointGroup>
            <rect>
                <x1>3096</x1><y1>3715</y1>
                <x2>4005</x2><y2>9861</y2>
            </rect>
        </item>
    </eventInfo>
    <sourceDataInfo>
        <dataType>0</dataType>
        <width>1280</width>
        <height>720</height>
        <sourceBase64Length>400924</sourceBase64Length>
        <sourceBase64Data>... base64 JPEG ...</sourceBase64Data>
    </sourceDataInfo>
    <targetListInfo>
        <item>
            <targetId>716</targetId>
            <targetType>person</targetType>
            <targetImageData>
                <dataType>0</dataType>
                <width>336</width>
                <height>448</height>
                <targetBase64Length>78796</targetBase64Length>
                <targetBase64Data>... base64 JPEG ...</targetBase64Data>
            </targetImageData>
        </item>
    </targetListInfo>
</config>

    Confirmed Detection Types

    These detection types have been tested with NVR v2.0 firmware:

    regionIntrusion (Perimeter Intrusion) Confirmed

    Triggered when a person or vehicle enters a defined zone.

    Field Description
    smartType regionIntrusion
    boundary area
    pointGroup Polygon coordinates defining the intrusion zone
    rect Bounding box of detected target
    targetType person or car

    IP Camera equivalent: PEA with <perimeter> block

    lineCrossing (Tripwire / Line Crossing) Confirmed

    Triggered when a person or vehicle crosses a defined line.

    Field Description
    smartType lineCrossing
    boundary tripwire
    directionLine Start and end points of the tripwire line
    rect Bounding box of detected target
    targetType person or car 
    <eventInfo>
    <item>
        <eventId>1409</eventId>
        <targetId>1309</targetId>
        <boundary>tripwire</boundary>
        <directionLine>
            <startPoint><x>3579</x><y>2550</y></startPoint>
            <endPoint><x>3655</x><y>9797</y></endPoint>
        </directionLine>
        <rect>
            <x1>3494</x1><y1>4409</y1>
            <x2>4261</x2><y2>9791</y2>
        </rect>
    </item>
</eventInfo>
    Note: The NVR does not include crossing direction (A→B vs B→A) in the webhook. The directionLine defines the tripwire position, not which way the target crossed.

    IP Camera equivalent: PEA with <tripwire> block

    Image Options

    The NVR can be configured to send different image combinations with each alarmData post:

    Setting What’s Sent Typical Size XML Sections
    Both Images Overview + target crop ~524 KB sourceDataInfo + targetListInfo with targetImageData
    Original Only Overview only ~418 KB sourceDataInfo only
    Target Only Target crop only ~92 KB targetListInfo with targetImageData only
    No Images Event data only ~1 KB Neither (but targetListInfo still has targetId and targetType)
    Key point: targetListInfo is always present with at least targetId and targetType, even when images are disabled. You always get target classification data.

    Detection Types – Testing in Progress

    The following detection types are available on Viewtron AI cameras but have not yet been tested through NVR forwarding. We will update this section as testing continues.

    IP Camera Code Description Expected NVR smartType
    VEHICE / VEHICLE License Plate Recognition TBD
    VFD Face Detection TBD
    VFD_MATCH Face Recognition / Match TBD
    VSD Video Metadata (AI object detection) TBD
    AOIENTRY Region Entry TBD
    AOILEAVE Region Exit TBD
    PASSLINECOUNT Line Crossing Count TBD
    CDD Crowd Density Detection TBD

    If you test any of these through an NVR, please reply to this post with the smartType value you observe.

    Timestamps

    NVR v2.0 uses 16-digit Unix microsecond timestamps:

    <currentTime>1772056914604000</currentTime>

    To convert to seconds, divide by 1,000,000:

    • 1772056914604000 ÷ 1,000,000 = 1772056914.604 (Unix timestamp with milliseconds)

    Developer Resources

    Python API Server: https://github.com/mikehaldas/IP-Camera-API

    The server includes:

    • server.py – HTTP server that accepts webhooks from both IP Cameras and NVRs
    • viewtron.py – Parser classes for v1.x (IP Camera) and v2.0 (NVR) formats
    • Automatic image extraction and saving
    • CSV event logging

    Clone and run:

    git clone https://github.com/mikehaldas/IP-Camera-API.git
cd IP-Camera-API
pip install xmltodict
python3 server.py

    Related Posts

  • Author
    Posts
Viewing 1 post (of 1 total)
  • You must be logged in to reply to this topic.