Camio can programmatically notify your preferred callback endpoints when important events happen. You define domain-level endpoints that receive callbacks for specific Event Types. The incident.created Event is triggered whenever a stream health counter is greater than zero.

Domain Registration

Your domain must be registered prior to using callback Endpoints, If your domain isn't already registered, then please send the email address you'd like to designate as your primary domain admin to support@camio.com to register your domain.

Domain-level Callback Endpoints

Open https://camio.com/domains after signing in as the domain admin designated above.
Enter your domain and press the Find button. (You can also specify the domain in the query string like https://camio.com/domains/?domain=acme.com)
Enter the HTTP Request to be triggered:
1. HTTP Method that's typically POST or PUT, but any of the commands are supported.
2. URL of the new Endpoint
3. HTTP Headers as JSON key/value pairs. The example below is:
```
{
    "Authorization": "token XYZPDQ",
    "Content-Type": "application/json"
}
```
4. Event Types that trigger the requests sent to this new Endpoint.
5. Min Upload Queue Length for Incident only for the creation of incidents when upload_queue_length exceeds the value specified. (see 2024-05-07 release notes)

Event Types

The Event Types currently include:

camera.created
camera.updated
camera.deleted
device.deleted
hook.created
hook.deleted
incident.created
pacs.events.created
zone.created
zone.updated
zone.deleted

incident.created

The types of incidents included in incident.created are counter values greater than zero for:

stream_changed_offline_count
movies_discarded_count
events_purged_count
movies_purged_count
segmentation_process_restart_count (only when greater than 15 within a 15-minute period)

and counter values greater than your value for min_upload_queue_length_for_incident_creation specified in your domain settings for:

upload_queue_length

incident.created payload

The payload of the POST to the URL includes "data", "id" and "type" like this example for incident.created caused by a failure to connect to a camera stream on the LAN (AKA segmentation_process_restart_count):

{
    "data": {
        "object": {
            "incident": {
                "camera_name": "Front Entrance",
                "counter_events": {
                    "segmentation_process_restart_count": {
                        "counter": "segmentation_process_restart_count",
                        "description": "47 \\u003e 0 means the network connection to the video stream is unstable have restarted 47 times in 15 minutes.",
                        "value": 47
                    }
                },
                "date": "2021-04-30T19:13:42.317-0000",
                "type": "incident"
            },
            "user": {
                "email": "hq-cams@acme.com",
                "user_id": "56X126755830642533906524"
            }
        }
    },
    "id": "f58a5ef2-fbc7-407b-bdeb-536bfde767da",
    "type": "incident.created"
}

See the definition of each counter.

pacs.events.created

The pacs.events.created event type is used to relay only those events from a Physical Access Control System (PACS) that are NOT mapped to any video stream. For example, if a door reader on the rooftop has no camera with a view of that door, then you may still want the entry.ajar.started PACS event to trigger a callback to your Endpoint even if there is no camera that can see that rooftop door.

pacs.events.created payload

Each PACS has a different way of representing doors/readers, timestamps, and events. Camio aims to pass along the PACS event as JSON that retains the full fidelity of the originating PACS event. In addition, Camio inserts a camio_metadata field into each event to provide a consistent way to reference the entry_id, date, labels, and optionally source_server to help.

For example, here's a pacs.events.created payload from Lenel OnGuard:

{
  "id": "4d547b24-cac3-4ade-850b-3e69197016f3",
  "type": "pacs.events.created",
  "data": {
    "object": {
      "user": {
        "user_id": "u123",
        "email": "test@acme.com",
      },
      "domain": "acme.com",
      "events": [
        {
          "badge_id": 0,
          "controller_id": 1,
          "cardholder_key": 0,
          "event_type": 4,
          "event_subtype": 10,
          "device_id": 1,
          "device_name": "Rooftop Reader 1",
          "serial_number": 1611881197,
          "timestamp": "2021-01-29T01:14:33.000000",
          "camio_metadata": {
            "entry_id": "1_1",
            "date": "2021-01-29T01:14:33.000-0000",
            "labels": [
              "onguard:entry.ajar.started:2021-01-29T01:14:33.000-0000",
              "entry.ajar.started",
              "integration:onguard"
            ]
          }
        }
      ],
      "source_server": "apac.int.acme.com:443"
    }
  }
}

Domains API

Please see https://api.camio.com/#domains for API documentation.

How do I register callback endpoints for my domain?