Monitoring Webhook Guide

Configure tenant-scoped webhook delivery and interpret the Cisco Spaces IoT payload schema.

Configure a webhook notification target #

  1. Open the tenant, then create a Webhook Notification Target.
  2. Enter a tenant-unique name and an absolute HTTPS endpoint URL, including the integration-specific path.
  3. Choose POST, PUT, or PATCH and add any required headers or query parameters as JSON objects.
  4. Select whether the AP list contains all tracked APs or only APs currently alerting for at least one monitored concept.
  5. Add the target to an active Notification Profile, then assign that profile to the desired sites.
  6. Select Send Test and confirm that the destination returns a 2xx response.
Tenant boundary

A target and every Notification Profile that contains it belong to one tenant. API validation and runtime delivery reject cross-tenant relationships.

Transport and authentication #

Setting Behavior
Endpoint URL Must be an absolute HTTPS URL with a DNS hostname. Credentials and query strings are configured separately and are rejected in the URL.
Method POST, PUT, or PATCH with a UTF-8 JSON request body.
Headers Customer-defined JSON object. Use Authorization here for bearer, basic, or integration-specific credentials.
Query parameters Customer-defined JSON object appended by the HTTP client.
Timeout 1 to 60 seconds. Redirects are not followed.
Self-signed TLS Off by default. When enabled, the request remains HTTPS but server-certificate verification is disabled for that target.
HMAC signing Optional HMAC-SHA256 over the exact request bytes. The selected header receives sha256=<hex digest>.

Payload envelope #

Webhook schema version 1.0
{
  "schema_version": "1.0",
  "event": {
    "id": "<monitoring-execution-uuid>",
    "type": "monitoring.spaces_iot.alert",
    "created_at": "2026-09-22T15:30:00+00:00",
    "test": false
  },
  "tenant": {
    "spaces_tenant_id": "123456789",
    "name": "Example Tenant"
  },
  "monitoring": {
    "execution_id": "<monitoring-execution-uuid>",
    "configuration_id": "<configuration-uuid>",
    "monitoring_profile": {"id": "<profile-uuid>", "name": "Production IoT"},
    "concept_key": "spaces_iot_infra",
    "status": "critical",
    "alert_mode": "total_configured_noncompliant",
    "triggered_by": "scheduler",
    "started_at": "2026-09-22T15:29:40+00:00",
    "completed_at": "2026-09-22T15:30:00+00:00",
    "report_url": "https://wasense.example/monitoring/executions/<uuid>/"
  },
  "building": {
    "id": "building-101",
    "name": "Headquarters",
    "type": "BUILDING",
    "assigned_intent": {
      "profile_id": "7",
      "profile_name": "Transmit + Advanced Gateway",
      "source": "assigned_profile",
      "fingerprint": "<intent-fingerprint>",
      "assignment_location_id": "building-101",
      "assigned_major": 1201,
      "effective_major": 1201,
      "values": {
        "profile_type": "ibeacon",
        "expected_uuid": "...",
        "expected_major": 1201,
        "expected_gateway_mode": "advanced",
        "ble_mode": "transmit"
      }
    }
  },
  "buildings": [
    {
      "id": "building-101",
      "name": "Headquarters",
      "type": "BUILDING",
      "assigned_intent": {
        "profile_id": "7",
        "profile_name": "Transmit + Advanced Gateway",
        "source": "assigned_profile",
        "fingerprint": "<intent-fingerprint>",
        "assignment_location_id": "building-101",
        "assigned_major": 1201,
        "effective_major": 1201,
        "values": {
          "profile_type": "ibeacon",
          "expected_uuid": "...",
          "expected_major": 1201,
          "expected_gateway_mode": "advanced",
          "ble_mode": "transmit"
        }
      }
    }
  ],
  "metadata": {
    "payload_scope": "alerting_aps",
    "tracked_ap_count": 125,
    "included_ap_count": 3,
    "alerting_ap_count": 3,
    "thresholds": {},
    "floor_rollups": [],
    "api_summary": {},
    "summary_counts": {}
  },
  "category_counts": {
    "overall": {"tracked": 125, "alerting": 3, "healthy": 121, "unknown": 1},
    "concepts": {
      "iox_app": {"healthy": 123, "noncompliant": 2},
      "beacon": {"healthy": 124, "noncompliant": 1}
    }
  },
  "aps": [
    {
      "mac": "aa:bb:cc:dd:ee:ff",
      "name": "hq-floor-2-ap-17",
      "model": "CW9166I",
      "serial": "...",
      "pid": "CW9166I",
      "floor": {"id": "floor-202", "name": "Second Floor"},
      "building": {"id": "building-101", "name": "Headquarters"},
      "status": "DOWN",
      "connected": false,
      "software_version": "17.15.3",
      "ble_enabled": true,
      "gateway_mode": "advanced",
      "scan_mode": "full",
      "app_status": "DOWN",
      "app_version": "1.2.3",
      "last_observed_at": "2026-09-22T15:30:00+00:00",
      "intent": {
        "source": "published_device",
        "profile_id": "7",
        "profile_name": "Transmit + Advanced Gateway",
        "fingerprint": "<device-intent-fingerprint>",
        "values": {}
      },
      "monitoring": {
        "state": "alerting",
        "alerting": true,
        "alerting_concepts": ["iox_app"],
        "last_healthy_at": "2026-09-22T15:20:00+00:00",
        "last_run": {
          "execution_id": "<monitoring-execution-uuid>",
          "evaluated_at": "2026-09-22T15:30:00+00:00",
          "completed_at": "2026-09-22T15:30:00+00:00"
        },
        "concepts": {
          "iox_app": {
            "state": "noncompliant",
            "reason": "IOx app channel is stale.",
            "configuration_status": "compliant",
            "operational_status": "degraded",
            "configuration_reasons": [],
            "operational_reasons": ["IOx app channel is stale."],
            "data_quality_reasons": [],
            "state_since": "2026-09-22T15:25:00+00:00",
            "last_evaluated_at": "2026-09-22T15:30:00+00:00",
            "last_changed_at": "2026-09-22T15:25:00+00:00",
            "last_healthy_at": "2026-09-22T15:20:00+00:00",
            "last_noncompliant_at": "2026-09-22T15:25:00+00:00",
            "consecutive_healthy_runs": 0,
            "consecutive_noncompliant_runs": 2,
            "flap_count": 1
          }
        }
      }
    }
  ]
}

schema_version identifies the contract version. Consumers should accept additive fields within the same major version. event.id is the monitoring execution UUID and is suitable as an idempotency key. event.test is true only for the configuration test request.

tenant identifies the owning tenant. monitoring gives the configuration, reusable monitoring profile, alert mode, execution timing, result status, trigger source, and detail-report link.

Building intent #

For a single-building execution, building contains the same record as the only entry in buildings. For a building-equivalent network that resolves to multiple buildings, building is null and consumers should iterate buildings.

assigned_intent names the effective tenant or assigned intent profile. assigned_major is the explicit location assignment; effective_major is the value after tenant-default and named-profile inheritance. The values object contains the effective IoT settings used for compliance evaluation.

Metadata and category counts #

metadata.tracked_ap_count is the complete population evaluated by the run. included_ap_count is the number actually present in aps; the values differ when the profile selects alerting APs only. Thresholds, floor rollups, API availability, and the monitor's native summary totals provide the building-level view.

category_counts.overall gives tracked, alerting, healthy, and unknown AP counts. category_counts.concepts groups state and data quality counts by monitored concept, initially iox_app and beacon.

AP records and health timing #

Each AP includes identity, model and software data when available, plain-text floor name and Spaces floor ID, building identity, current operational values, effective device intent, and per-concept monitoring state.

monitoring.alerting is true when at least one concept is currently operationally or configurationally noncompliant. Per-concept last_healthy_at is the last successful evaluation for that concept. The AP-level value is conservative: it is the earliest last-healthy timestamp across applicable concepts and is null until every applicable concept has a recorded healthy evaluation.

The alerting-only scope changes only the aps array. Counts and metadata always describe the full monitored building population so receivers can understand impact without receiving every healthy AP record.

Delivery behavior #

Webhook delivery uses the mapped monitoring profile's alert mode, threshold, recent-transition window, change-only suppression, and floor suppressions. It is independent of the Webex enable switch: either or both channels may deliver an alert. Each enabled mapped webhook is attempted separately, and one destination failure does not prevent attempts to the others.

A test request validates network reachability, TLS behavior, method, headers, query parameters, authentication, and optional signing. Its monitoring and building objects are null or empty and its AP list contains no production data.