On-Prem to Cloud: Vendor-Managed Integrations

Context

Convergint is evolving how we integrate with physical security platforms.

Historically, many integrations to on-prem systems have relied on on-prem agents/connectors that Convergint develops, distributes, and maintains. This works, but it pushes ongoing complexity onto Convergint (SDK/version drift, customer network constraints, credential handling, upgrades, and site-specific edge cases).

This document describes the next evolution: vendors own and operate the on-prem integration surface (if any) and Convergint integrates cloud-to-cloud. We “meet in the cloud.”

This is a high-level document intended to align on the integration contract (inventory + events). We expect to collaborate on the design specifics with each vendor.

What changes

Why vendors are best positioned

What We Need From Vendors

Today’s World (On-Prem Agents Owned by Convergint)

Convergint-owned agent runs at the customer site and forwards inventory/events to Convergint Cloud.

Today's World

Target World (Vendor-Managed Cloud Model)

Vendor-owned connector (if any) runs at the customer site; Convergint integrates directly with the vendor cloud via APIs + webhooks.

Target World

Scope

We’re looking for two core capabilities from a vendor’s cloud platform:

  1. Asset Inventory
    • Pull a full list of devices/assets for a given Convergint customer/site.
    • At minimum, inventory must reflect each device’s latest known status.
    • Inventory API must support pagination (inventories can contain hundreds or thousands of devices).
    • Inventory API must support filtering by site/location (e.g., “for this site, return all assets”).
  2. Live Events (Push Preferred)
    • Baseline: device health events (online/offline/last_seen) delivered via webhooks. (If webhooks are not yet available, Convergint can poll inventory as an interim measure, provided each asset includes its last known status.)
    • Preferred: additional event families the vendor already exposes through on-prem SDKs (alarms/trouble, access events, video/VMS events, etc.).

Every payload (inventory or event) must include enough metadata to reliably map vendor entities to the correct Convergint customer and site.

Integration Model

Mapping / Binding (Tenant + Site)

We prefer credential-bound integrations:

This is consistent with how many modern cloud integrations behave today, where vendor “Account/Org” and “Location/Site” identifiers exist and can be used for resolution.

Mapping/Binding

Minimum Data Requirements

At a minimum, we need the following fields.

Identifier Best Practice: We strongly recommend using UUIDs (or equivalent globally unique identifiers) for all entity IDs—devices, sites, accounts, and events. Globally unique IDs simplify event processing and eliminate ambiguity when correlating devices across locations.

Account Metadata (via API key)

Site Metadata (per site)

Inventory (per device)

Nice to Have

Health Events (baseline)

Additional Events (preferred)

The vendor should expose an event catalog. Convergint prefers webhooks for all event families the platform can publish, but will start with health.

Examples of event families we may adopt (depending on vendor support):

Sample API Request/Response

The following examples illustrate the expected shape of API responses. These are illustrative—vendors may adapt field names and structure as needed, as long as the required data is present.

Account API

Returns the account associated with the current API key. This solves the bootstrap problem: Convergint can discover which vendor account the credentials belong to.

GET /api/v1/account

{
  "account_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "name": "Acme Security Corp"
}

Sites API (paginated)

Since the API key is bound to a single account, the account is implicit.

GET /api/v1/account/sites?page=1&per_page=50

{
  "sites": [
    {
      "site_id": "5e6693c0-091d-47a2-b90a-6c15531b3c50",
      "name": "US - 101 Chicago, IL",
      "address": "2000 Center Drive, Suite 315A, Hoffman Estates, IL 60192",
      "timezone": "America/Chicago"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total_pages": 3,
    "total_count": 127
  }
}

Inventory API (paginated)

GET /api/v1/sites/{site_id}/inventory?page=1&per_page=100

{
  "devices": [
    {
      "device_id": "652efeac-8567-4253-9d61-bbc842863d33",
      "name": "Front Lobby Door",
      "type": "door",
      "status": "online",
      "mac_address": "00:0f:e5:14:b2:1e",
      "site_id": "5e6693c0-091d-47a2-b90a-6c15531b3c50",
      "parent_id": "b3a1f7d2-4e89-4c12-a5d6-9f8e7c6b5a43"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 100,
    "total_pages": 5,
    "total_count": 487
  }
}

Health Event Payload (webhook)

{
  "event_id": "698219ad-4de9-896d-3be0-66cb00000001",
  "event_type": "health",
  "device_id": "652efeac-8567-4253-9d61-bbc842863d33",
  "timestamp": "2026-02-04T14:32:00Z",
  "account_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "site_id": "5e6693c0-091d-47a2-b90a-6c15531b3c50",
  "data": {
    "status": "offline"
  }
}

Initially, we are focused on health events. However, this structure should be flexible enough to accommodate other event types (access, alarm, etc.) in the future. The event_type field distinguishes between event families, and data contains the event-specific attributes.

Target Workflows

1. Inventory Sync (Poll)

Inventory Sync

2. Real-Time Events (Push via Webhooks)

Webhooks

Fallback Behavior (Empty / Delayed / Offline)

We expect real-world gaps. A vendor integration should support:

Integration Lifecycle

  1. Onboarding
    • Configure credentials (API key / OAuth app).
    • Bind vendor account + site(s) to Convergint customer/site records.
    • Configure webhook destination + signing secret.
  2. Collection
    • Poll inventory on a schedule.
    • Receive events continuously via webhooks.
  3. Data Mapping
    • Convergint maps vendor device taxonomy and statuses into a consistent Convergint schema.
  4. Operational Expectations
    • Signed webhooks with replay protection (timestamp window recommended).
    • Retry semantics and idempotency to prevent duplicates.

Authentication and Webhook Security

API Authentication: We recommend JWT-based authentication. Convergint generates a private key per account from the vendor’s administration console. Convergint uses this key to mint short-lived tokens (RS256) for each API request, and the vendor verifies using the corresponding public key. This approach eliminates long-lived API keys and ensures tokens expire quickly if compromised.

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJjb252ZXJnaW50IiwiaWF0IjoxNzA3MDYyNDAwLCJleHAiOjE3MDcwNjI3MDB9.signature...

Decoded payload (token expires in 1 hour):

{
  "iss": "convergint",
  "iat": 1707062400,
  "exp": 1707066000
}

Webhook Signatures: All webhook payloads should be signed using HMAC-SHA256 with a shared secret. The signature should be included in a request header (e.g., X-Webhook-Signature), along with a timestamp for replay protection. Convergint verifies the signature before processing any event.

X-Webhook-Signature: sha256=5d5b09f6dcb2d53a93f17d2f4ad705c8e8a0123456789abcdef...
X-Webhook-Timestamp: 1707062400

Signature is computed as HMAC-SHA256(request_body, secret).

Webhook Management API (nice to have): To enable self-service configuration, we prefer an API for webhook lifecycle management.

Create webhook:

POST /api/v1/webhooks

{
  "name": "Convergint Insights",
  "target_url": "https://app.convergint.com/api/webhooks/vendor",
  "status": "active"
}

Response (includes generated secret):

{
  "webhook_id": "d4e5f6a7-1234-5678-90ab-cdef12345678",
  "name": "Convergint Insights",
  "target_url": "https://app.convergint.com/api/webhooks/vendor",
  "status": "active",
  "secret": "whsec_5d5b09f6dcb2d53a93f17d2f4ad705c8..."
}

List webhooks:

GET /api/v1/webhooks

{
  "webhooks": [
    {
      "webhook_id": "d4e5f6a7-1234-5678-90ab-cdef12345678",
      "name": "Convergint Insights",
      "target_url": "https://app.convergint.com/api/webhooks/vendor",
      "status": "active"
    }
  ]
}

Delete webhook:

DELETE /api/v1/webhooks/{webhook_id}

We’re happy to discuss the specifics of authentication and webhook setup during our working sessions.

Next Steps (Collaborative)

We recognize this model may be net-new work for vendors that historically integrate primarily via on-prem SDKs.

If you’re open to pursuing this, we’d like to collaborate on the design and implementation details together.

What we can provide

For questions or next steps, contact:

Ryan Johnston – ryan.johnston@convergint.com Director Engineering

Juan Pemberthy – juan.pemberthy@convergint.com Principal Software Engineer