Event Handling

The globalMOO API provides event notifications for important state changes and asynchronous operations.

Event Format

Events follow this structure:

{
    "id": 123,
    "created_at": "2025-01-31T10:00:00.000Z",
    "updated_at": "2025-01-31T10:00:00.000Z",
    "disabled_at": null,
    "name": "project.created",
    "subject": "optional-subject-id",
    "data": {
        // Event-specific data object
    }
}

Event Types

Event Name	Description	Data Type
project.created	New project created	Project
inverse.suggested	New inverse step suggested	Inverse

SDK Event Handling

Python

from globalmoo.client import Client

client = Client()

# Handle webhook payload
event = client.handle_event(webhook_payload)

# Event data is automatically mapped to correct type
if event.name == "project.created":
    project = event.data  # Project object
    print(f"Project {project.id} created")
elif event.name == "inverse.suggested":
    inverse = event.data  # Inverse object
    print(f"Inverse step {inverse.iteration} suggested")

PHP

use GlobalMoo\Client;

$client = new Client();

// Handle webhook payload
$event = $client->handleEvent($webhookPayload);

// Event data is automatically mapped to correct type
switch ($event->name) {
    case 'project.created':
        $project = $event->data;  // Project object
        echo "Project {$project->id} created";
        break;
    case 'inverse.suggested':
        $inverse = $event->data;  // Inverse object
        echo "Inverse step {$inverse->iteration} suggested";
        break;
}

Node.js

const { Client } = require('globalmoo');

const client = new Client();

// Handle webhook payload
const event = client.handleEvent(webhookPayload);

// Event data is automatically mapped to correct type
switch (event.name) {
    case 'project.created':
        const project = event.data;  // Project object
        console.log(`Project ${project.id} created`);
        break;
    case 'inverse.suggested':
        const inverse = event.data;  // Inverse object
        console.log(`Inverse step ${inverse.iteration} suggested`);
        break;
}

Validation & Error Handling

Events are validated before processing:

1. Basic JSON validation

2. Required fields check

3. Event name validation

4. Data type mapping

5. Field type validation

Possible exceptions:

• InvalidArgumentException: Invalid JSON or missing fields

• InvalidEventException: Unknown event type

• ValidationException: Invalid data format

Example error handling:

try:
    event = client.handle_event(payload)
except InvalidArgumentException as e:
    print(f"Invalid event format: {e}")
    # Log error, request retransmission
except InvalidEventException as e:
    print(f"Unknown event type: {e}")
    # Log error, notify administrators
except ValidationException as e:
    print(f"Invalid event data: {e}")
    # Log error, investigate data corruption

Best Practices

1. Always validate event payloads

2. Use type-safe event handling

3. Implement idempotency checks

4. Log event processing

5. Handle errors gracefully

6. Process events asynchronously

7. Monitor event throughput

Integration Example

Complete webhook handler example:

from flask import Flask, request
from globalmoo.client import Client
from globalmoo.exceptions import GlobalMooException

app = Flask(__name__)
client = Client()

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    try:
        # Get raw payload
        payload = request.get_data().decode('utf-8')
        
        # Process event
        event = client.handle_event(payload)
        
        # Handle specific events
        if event.name == "project.created":
            handle_new_project(event.data)
        elif event.name == "inverse.suggested":
            handle_inverse_suggestion(event.data)
            
        return {'status': 'success'}, 200
        
    except GlobalMooException as e:
        # Log error details
        print(f"Error processing webhook: {e}")
        return {'error': str(e)}, 400
        
def handle_new_project(project):
    """Handle new project creation event"""
    print(f"New project {project.id} created")
    # Add project setup logic
    
def handle_inverse_suggestion(inverse):
    """Handle new inverse suggestion event"""
    print(f"Inverse step {inverse.iteration} suggested")
    # Add inverse processing logic