Webhook Events

Receive real-time notifications about agent events

POST /v1/webhooks

Coming soon! Configure webhooks to receive real-time notifications about agent events and state changes.

Planned Event Types

• agent.created - New agent instance created
• agent.state_changed - Agent state transition occurred
• memory.consolidated - Memory consolidation completed
• tool.executed - Tool function was called
• error.occurred - Error or exception in agent processing

Example Webhook Configuration

{
  "url": "https://your-app.com/webhooks/arkos",
  "events": ["agent.state_changed", "tool.executed"],
  "secret": "webhook_secret_key",
  "active": true
}

Example Webhook Payload (Planned)

{
  "event": "agent.state_changed",
  "timestamp": "2024-01-15T14:30:00Z",
  "agent_id": "default",
  "data": {
    "previous_state": "waiting_for_input",
    "current_state": "processing",
    "transition_reason": "user_input_received"
  },
  "signature": "sha256=..."
}

Security

Webhooks will include HMAC-SHA256 signatures for payload verification:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Webhook functionality is not yet implemented. This feature is planned for a future release to enable event-driven integrations.