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
project.created
New project created
Project
inverse.suggested
New inverse step suggested
Inverse
SDK Event Handling
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")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;
}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:
Basic JSON validation
Required fields check
Event name validation
Data type mapping
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 corruptionBest Practices
Always validate event payloads
Use type-safe event handling
Implement idempotency checks
Log event processing
Handle errors gracefully
Process events asynchronously
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 logicLast updated