Skip to content

# Event Subscription Tool

The Event Subscription tool provides functionality to subscribe to and monitor real-time events from your Home Assistant instance.

## Features

- Subscribe to Home Assistant events
- Monitor specific entities
- Domain-based monitoring
- Event filtering
- Real-time updates
- Event history
- Custom event handling
- Connection management

## Usage

### REST API

    POST /api/events/subscribe
    DELETE /api/events/unsubscribe
    GET /api/events/subscriptions
    GET /api/events/history

### WebSocket

    // Subscribe to events
    {
        "type": "subscribe_events",
        "event_type": "optional_event_type",
        "entity_id": "optional_entity_id",
        "domain": "optional_domain"
    }

    // Unsubscribe from events
    {
        "type": "unsubscribe_events",
        "subscription_id": "required_subscription_id"
    }

### Server-Sent Events (SSE)

    GET /api/events/stream?event_type=state_changed&entity_id=light.living_room

## Event Types

- `state_changed`: Entity state changes
- `automation_triggered`: Automation executions
- `scene_activated`: Scene activations
- `device_registered`: New device registrations
- `service_registered`: New service registrations
- `homeassistant_start`: System startup
- `homeassistant_stop`: System shutdown
- Custom events

## Examples

### Subscribe to All State Changes

    const response = await fetch('http://your-ha-mcp/api/events/subscribe', {
        method: 'POST',
        headers: {
            'Authorization': 'Bearer your_access_token',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            "event_type": "state_changed"
        })
    });

### Monitor Specific Entity

    const response = await fetch('http://your-ha-mcp/api/events/subscribe', {
        method: 'POST',
        headers: {
            'Authorization': 'Bearer your_access_token',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            "event_type": "state_changed",
            "entity_id": "light.living_room"
        })
    });

### Domain-Based Monitoring

    const response = await fetch('http://your-ha-mcp/api/events/subscribe', {
        method: 'POST',
        headers: {
            'Authorization': 'Bearer your_access_token',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            "event_type": "state_changed",
            "domain": "light"
        })
    });

### SSE Connection Example

    const eventSource = new EventSource(
        'http://your-ha-mcp/api/events/stream?event_type=state_changed&entity_id=light.living_room',
        {
            headers: {
                'Authorization': 'Bearer your_access_token'
            }
        }
    );

    eventSource.onmessage = (event) => {
        const data = JSON.parse(event.data);
        console.log('Event received:', data);
    };

    eventSource.onerror = (error) => {
        console.error('SSE error:', error);
        eventSource.close();
    };

## Response Format

### Subscription Response

    {
        "success": true,
        "data": {
            "subscription_id": "sub_123",
            "event_type": "state_changed",
            "entity_id": "light.living_room",
            "created_at": "2024-02-05T12:00:00Z"
        }
    }

### Event Message Format

    {
        "event_type": "state_changed",
        "entity_id": "light.living_room",
        "data": {
            "old_state": {
                "state": "off",
                "attributes": {},
                "last_changed": "2024-02-05T11:55:00Z"
            },
            "new_state": {
                "state": "on",
                "attributes": {
                    "brightness": 255
                },
                "last_changed": "2024-02-05T12:00:00Z"
            }
        },
        "origin": "LOCAL",
        "time_fired": "2024-02-05T12:00:00Z",
        "context": {
            "id": "context_123",
            "parent_id": null,
            "user_id": "user_123"
        }
    }

### Subscriptions List Response

    {
        "success": true,
        "data": {
            "subscriptions": [
                {
                    "id": "sub_123",
                    "event_type": "state_changed",
                    "entity_id": "light.living_room",
                    "created_at": "2024-02-05T12:00:00Z",
                    "last_event": "2024-02-05T12:05:00Z"
                }
            ]
        }
    }

## Error Handling

### Common Error Codes

- `404`: Event type not found
- `401`: Unauthorized
- `400`: Invalid subscription parameters
- `409`: Subscription already exists
- `429`: Too many subscriptions

### Error Response Format

    {
        "success": false,
        "message": "Error description",
        "error_code": "ERROR_CODE"
    }

## Rate Limiting

- Default limits:
- Maximum subscriptions: 100 per client
- Maximum event rate: 1000 events per minute
- Configurable through environment variables:
- `EVENT_SUB_MAX_SUBSCRIPTIONS`
- `EVENT_SUB_RATE_LIMIT`
- `EVENT_SUB_RATE_WINDOW`

## Best Practices

1. Use specific event types when possible
2. Implement proper error handling
3. Handle connection interruptions
4. Process events asynchronously
5. Implement backoff strategies
6. Monitor subscription health
7. Clean up unused subscriptions
8. Handle rate limiting gracefully

## Connection Management

- Implement heartbeat monitoring
- Use reconnection strategies
- Handle connection timeouts
- Monitor connection quality
- Implement fallback mechanisms
- Clean up resources properly

## See Also

- SSE Statistics
- Device Control
- Automation Management

February 5, 2025
February 5, 2025
Was this page helpful?
Thanks for your feedback!
Thanks for your feedback! Please consider creating an issue to help us improve.

#### Cookie consent

We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.

- Google Analytics
- GitHub

Manage settings