Alerts API Overview

Event monitoring and notification subscription service for Lamassu IoT Platform

Introduction

The Alerts API provides event monitoring and notification capabilities for the Lamassu IoT Platform. Users can subscribe to specific event types and receive notifications through various channels when events occur.

Base URL

/api/alerts/v1

Authentication

All Alerts API endpoints require Bearer token authentication using JWT tokens.

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://your-domain.com/api/alerts/v1/events/latest

API Groups

The Alerts API is organized into two main groups:

Events

Inspect and monitor the latest events per event type:

• Retrieve the most recent event for each event type
• View event metadata including timestamp and occurrence count

Subscriptions

Manage user alert subscriptions:

• List all subscriptions for a user
• Subscribe to specific event types
• Unsubscribe from events
• Configure notification channels
• Set conditional filters for events

Key Features

Multi-Channel Delivery

Receive notifications via Email, Microsoft Teams, or custom webhooks

Conditional Filters

Subscribe to events with specific conditions using JSON Schema, JSONPath, or JavaScript expressions

Event Monitoring

Track the latest events and their occurrence counts per event type

Flexible Subscriptions

Each user can manage their own subscriptions independently

Supported Notification Channels

Email

Receive notifications via email:

{
  "type": "EMAIL",
  "name": "Security Alerts",
  "config": {
    "email": "[e-mail]"
  }
}

Microsoft Teams

Send notifications to Microsoft Teams channels:

{
  "type": "MSTEAMS",
  "name": "Operations Channel",
  "config": {
    "webhook_url": "https://outlook.office.com/webhook/..."
  }
}

Webhooks

Integrate with custom systems via HTTP webhooks:

{
  "type": "WEBHOOK",
  "name": "Custom Integration",
  "config": {
    "webhook_url": "https://api.example.com/alerts",
    "webhook_method": "POST"
  }
}

Subscription Conditions

Filter events using three condition types:

JSON Schema

Validate event payload against a JSON Schema:

{
  "type": "JSON-SCHEMA",
  "condition": "{\"properties\": {\"severity\": {\"enum\": [\"critical\", \"high\"]}}}"
}

JSONPath

Filter events using JSONPath expressions:

{
  "type": "JSON-PATH",
  "condition": "$.data.status == 'failed'"
}

JavaScript

Use JavaScript expressions for complex filtering:

{
  "type": "JAVASCRIPT",
  "condition": "event.data.count > 100 && event.data.severity === 'critical'"
}

Common Event Types

Typical event types in the Lamassu platform:

• Certificate Issued - New certificate issued
• Certificate Revoked - Certificate revoked
• Certificate Expiring - Certificate nearing expiration
• Device Enrolled - New device enrolled
• Device Removed - Device removed from system
• CA Created - New Certificate Authority created
• CA Expired - Certificate Authority expired
• DMS Created - New DMS instance created
• Enrollment Failed - Device enrollment failed

Common Use Cases

Monitor Critical Certificate Events

{
  "event_type": "certificate.revoked",
  "conditions": [
    {
      "type": "JSON-PATH",
      "condition": "$.data.ca_id == 'root-ca-1'"
    }
  ],
  "channel": {
    "type": "EMAIL",
    "config": {"email": "[e-mail]"}
  }
}

Alert on Enrollment Failures

{
  "event_type": "enrollment.failed",
  "channel": {
    "type": "MSTEAMS",
    "config": {"webhook_url": "https://..."}
  }
}

Track High-Value Device Changes

{
  "event_type": "device.removed",
  "conditions": [
    {
      "type": "JAVASCRIPT",
      "condition": "event.data.tags.includes('production') && event.data.tags.includes('critical')"
    }
  ],
  "channel": {
    "type": "WEBHOOK",
    "config": {
      "webhook_url": "https://api.example.com/alerts",
      "webhook_method": "POST"
    }
  }
}

Next Steps

Events

Monitor the latest events

Subscriptions

Manage alert subscriptions