Skip to main content

Webhook Event Notification API

Viewtron IP cameras and NVRs can push real-time AI detection events to your HTTP server as webhooks. When a camera detects a person, vehicle, face, or license plate, it sends an HTTP POST to your server with XML data containing the event details, bounding box coordinates, and optionally base64-encoded JPEG images of the scene and detected target.

No polling required — your server receives events the moment they happen. No cloud service, no monthly fees, no third-party dependencies. The camera posts directly to your server on your local network or over the internet.

What You Can Build​

  • Real-time alert systems — push notifications when AI detections occur
  • Event logging and analytics — record all detections with timestamps, images, and metadata
  • Custom automation — trigger actions (lights, relays, gates, alarms) based on detection events
  • Integration with VMS, SIEM, or building management systems
  • Multi-camera event aggregation and dashboards

Two Sources of Webhook Data​

SourceFormatSupports trajectSetup
IP Camera (direct)IPC v1.x XMLYesConfigure on camera via API or web interface
NVR (forwarded)NVR v2.0 XMLNoConfigure on NVR web interface

Recommended setup: Configure the NVR to forward alarm events (images included), and configure individual cameras to send traject real-time tracking data directly. Your server receives both streams simultaneously.

How It Works​

  1. Configure the webhook destination on the camera or NVR — your server's IP, port, and URL path
  2. Enable detection types you want to receive (perimeter, face, LPR, etc.)
  3. Start your HTTP server listening for POST requests
  4. Parse the XML when events arrive — use the Viewtron Python SDK (pip install viewtron) or Node.js SDK to handle parsing automatically
  5. Respond with success XML to keep the connection alive

Supported Detection Types​

IPC smartTypeNVR smartTypeDetection
PEA (intrusion)regionIntrusionHuman Detection / Intrusion
PEA (line cross)lineCrossingPerimeter / Line Crossing
VEHICEvehicleLicense Plate Recognition
VFDvideoFaceDetectFace Detection
PASSLINECOUNTtargetCountingByLinePeople Counting
TRAFFICtargetCountingByAreaPeople Counting
VSDvideoMetadataVideo Metadata (full-frame detection)
VFD_MATCHNot supportedFace Recognition Match (IPC only)

Webhook Message Types​

Every webhook POST is one of three message types:

TypePurposeSizeFrequency
keepaliveHeartbeat — confirms connection is active~300 bytesEvery 30-120 seconds
alarmStatusAlarm state change (on/off)~660 bytesOne per state change
alarmDataFull detection event with coordinates and images2 KB - 530 KBOne per detection

Configuring Webhooks via API​

Use SetHttpPostConfig to configure the webhook destination on IP cameras. The httpPostV2 system supports up to 3 URLs with independent event filtering:

<?xml version="1.0" encoding="UTF-8"?>
<config version="1.0" xmlns="http://www.ipc.com/ver10">
<httpPostV2><postUrlConf>
  <urlList type="list" count="1"><item>
    <urlId>1</urlId>
    <switch>true</switch>
    <url>
      <protocol>http</protocol>
      <domain><![CDATA[192.168.0.53]]></domain>
      <port>5002</port>
      <path><![CDATA[/API]]></path>
      <authentication>none</authentication>
    </url>
    <heatBeatSwitch>true</heatBeatSwitch>
    <keepaliveTimeval>90</keepaliveTimeval>
    <subscribeDateType type="list" count="5">
      <item>alarmStatus</item>
      <item>traject</item>
      <item>smartData</item>
      <item>sourceImage</item>
      <item>targetImage</item>
    </subscribeDateType>
    <subscriptionEvents type="list" count="1">
      <item>PERIMETER</item>
    </subscriptionEvents>
  </item></urlList>
</postUrlConf></httpPostV2>
</config>

Data Type Subscriptions (httpPostV2)​

Control what data each webhook URL receives:

Data TypeDescriptionPost Size
alarmStatusAlarm on/off state changes~660 bytes
trajectContinuous real-time target tracking~1.7 KB at ~7/sec
smartDataDetection event with coordinates~2-3 KB
sourceImageFull-frame JPEG (base64 in XML)~500 KB
targetImageCropped target JPEG (base64 in XML)Included with smartData
tip

Subscribe to smartData + sourceImage + targetImage to receive complete detection events with both overview and cropped target images in a single POST.

Server Response​

Your server must respond with this XML to keep the connection alive:

<?xml version="1.0" encoding="UTF-8"?>
<config version="1.0" xmlns="http://www.ipc.com/ver10">
  <status>success</status>
</config>

Receiving All Event Types​

The simplest way to receive all webhook event types. The SDK's ViewtronServer handles HTTP connections, keepalives, XML parsing, version detection, and routing — you just write the callback:

pip install viewtron
from viewtron import ViewtronServer
import os

IMG_DIR = "images"
os.makedirs(IMG_DIR, exist_ok=True)

def on_event(event, client_ip):
    print(f"[{event.category}] {event.get_alarm_description()} from {client_ip}")
    print(f"  Camera: {event.get_ip_cam()}")
    print(f"  Type: {event.get_alarm_type()}")

    # LPR-specific fields
    if event.category == "lpr":
        print(f"  Plate: {event.get_plate_number()}")
        print(f"  Group: {event.get_plate_group()}")

    # Face-specific fields (NVR v2.0)
    if event.category == "face":
        age = event.get_face_age()
        if age:
            print(f"  Age: {age}, Sex: {event.get_face_sex()}")

    # Save images
    overview = event.get_source_image_bytes()
    if overview:
        with open(f"{IMG_DIR}/{event.get_time_stamp()}-overview.jpg", "wb") as f:
            f.write(overview)

    target = event.get_target_image_bytes()
    if target:
        with open(f"{IMG_DIR}/{event.get_time_stamp()}-target.jpg", "wb") as f:
            f.write(target)

server = ViewtronServer(port=5002, on_event=on_event)
server.serve_forever()

See the Python SDK reference for the full list of methods and event classes.

Relevant API Endpoints​

EndpointPurposeReference
SetHttpPostConfigConfigure webhook destination and subscriptionsWebhook Config
GetHttpPostConfigRead current webhook configurationWebhook Config
GetAlarmStatusPoll current alarm stateAlarm Status

Integrations​

Viewtron webhook events also integrate with automation platforms via published packages:

PlatformPackageWhat It Does
Home Assistantviewtron-home-assistantAll detection events as native HA sensors — automate anything in Home Assistant
Node-REDnode-red-contrib-viewtronAll detection events direct to Node-RED flows — visual automation builder

Questions & Development Inquiries​

Mike Haldas is available for questions, consultation, and custom software development for Viewtron API related projects. Email details about your project to mike@viewtron.com.