Dynamic events (API)

The dynamic events endpoint is an HTTP service on your Netsocs instance that lets you create events on the platform in a fully dynamic way, without pre-registering the device, object, or event type.

Endpoint URL

Send requests with the POST method to the following URL (replace netsocs-server-instance with your deployment host, e.g. https://my-instance.example.com):

POST https://netsocs-server-instance/api/netsocs/dh/dynamic-events

The path relative to your API base is: /api/netsocs/dh/dynamic-events.

Authentication

Authentication for this endpoint is optional. If your instance has a token configured for dynamic events, send it as a Bearer token in the Authorization header:

Authorization: Bearer <your-token>

Create and manage these tokens under Settings, in Technologies → Dynamic events (the same area as device and video engine management). See Technologies for more context.

Behavior

In a single call, the platform may:

1. Register the source device (if it does not already exist).
2. Register the object associated with the event (if it does not already exist).
3. Register the event type (if it does not already exist).
4. Create the event.

This is suitable for external integrations, third-party systems, or any source that must emit events without prior manual configuration in the UI.

Request

Headers

Header	Value	Required
Content-Type	application/json	Yes
Authorization	Bearer <token>	No — only if a token is defined under Settings → Technologies → Dynamic events

Body (JSON)

{
  "source": {
    "device_name":   "string",
    "object_id":     "string",
    "object_domain": "string",
    "object_name":   "string",
    "object_type":   "string"
  },
  "event": {
    "event_type": {
      "event_type":          "string",
      "display_name":        "string",
      "display_description": "string"
    },
    "event_data": {
      "event_additional_properties": {
        "key": "value"
      },
      "images":      ["string"],
      "video_clips": ["string"]
    }
  }
}

source section (required)

Identifies the event origin: device and object.

Field	Type	Required	Description
device_name	string	Yes	Unique name of the originating device. Created automatically if missing.
object_id	string	Yes	Object identifier within the domain (do not embed the domain in this value).
object_domain	string	Yes	Logical domain (e.g. security, iot). A pattern like device_brand.object_type.functionality is suggested.
object_name	string	Yes	Human-readable object name.
object_type	string	Yes	Object type (e.g. video_channel, sensor, door).

The platform’s full object id is {object_domain}.{object_id} (e.g. domain security and id cam-01 → security.cam-01).

event section (required)

event_type

Field	Type	Required	Description
event_type	string	Yes	Unique event type id (e.g. motion_detected).
display_name	string	Yes	Label shown in the UI.
display_description	string	Yes	Short description of the event type.

If the event type already exists in the domain, existing settings are kept; otherwise it is created from the payload.

event_data

Field	Type	Required	Description
event_additional_properties	key-value object	No	Custom properties; values must be strings (string → string).
images	array of strings	No	Image URLs attached to the event.
video_clips	array of strings	No	Video clip URLs attached to the event.

Special property base64_image: inside event_additional_properties, the reserved key base64_image may hold a Base64-encoded image (with or without a data:image/...;base64, prefix). The platform decodes it, stores the file, and appends its URL to the event’s images list. Supported formats: JPEG, PNG, GIF, WEBP.

Responses

200 OK

Returns the created event, for example:

{
  "id": "event-uuid",
  "domain": "security",
  "event_type": "motion_detected",
  "rels": ["/objects/security.cam-01"],
  "images": [],
  "video_clips": [],
  "event_additional_properties": {},
  "created_at": "2026-02-18T10:30:00.000000000Z",
  "updated_at": "2026-02-18T10:30:00.000000000Z"
}

400 Bad Request

Required fields are missing or the JSON is invalid.

{
  "error": "source is required"
}

500 Internal Server Error

Internal failure while registering the device, object, or event.

Automatic behavior (summary)

Situation	Behavior
Device does not exist	Created as a generic device.
Device already exists	Reused unchanged.
Object does not exist	Created and linked to the device and domain.
Object already exists	Existing object is reused.
Event type does not exist	Created with the supplied name and description.
Event type already exists	Existing configuration is preserved.
base64_image is present	Decoded, stored, and URL added to images.

Important notes

• All source fields are required; any empty value yields 400 Bad Request.
• Do not include the domain inside object_id; the platform builds {object_domain}.{object_id}.
• created_at and updated_at are set by the platform in RFC 3339 UTC.
• The event id is an auto-generated UUID returned in the response.

Minimal example

POST https://netsocs-server-instance/api/netsocs/dh/dynamic-events
Content-Type: application/json

{
  "source": {
    "device_name":   "nvr-north-building",
    "object_id":     "cam-entrance-01",
    "object_domain": "netsocs_partner.video_channel.video_stream",
    "object_name":   "Main entrance camera",
    "object_type":   "camera"
  },
  "event": {
    "event_type": {
      "event_type":          "motion_detected",
      "display_name":        "Motion detected",
      "display_description": "Motion was detected in the monitored area"
    },
    "event_data": {
      "event_additional_properties": {
        "zone":       "entrance",
        "confidence": "0.92"
      },
      "images": []
    }
  }
}