Notifications & Alerts

Setting up notification systems for human-in-the-loop workflows.

Event-Based Notifications

Subscribe to HILT events to trigger notifications:

from leafmesh import LeafMesh

leafmesh = LeafMesh.from_store()   # the agency named by LEAFMESH_AGENCY_NAME in .env

async def notify_on_review_needed(event):
    """Triggered when a human agent receives a request"""
    session_id = event.session_id
    agent_name = event.data.get("agent_name", "unknown")

    # Send notification through your preferred channel
    await send_slack_notification(
        channel="#reviews",
        message=f"Review needed: {agent_name} (session: {session_id})"
    )

async def notify_on_timeout(event):
    """Triggered when a human doesn't respond in time"""
    session_id = event.session_id

    await send_slack_notification(
        channel="#reviews-urgent",
        message=f"TIMEOUT: Review expired for session {session_id}"
    )

# These notifications are triggered automatically via webhook_config in YAML.
# Configure the human agent's webhook_config to point to your notification service,
# which handles Slack, email, or other alerting.

Webhook Notifications

Point the human agent's webhook at your notification service. The service's address (and any header, query or token rows) is an Add custom record on Studio's Infrastructure page with service type Outbound webhook; connection: names it. An inline URL is refused at load. A human agent with no webhook_config is an Inbox seat and needs no record at all.

agents:
  urgent_reviewer:
    name: "urgent_reviewer"
    agent_type: "human"
    timeout: 120
    webhook_config:
      connection: "urgent-review-webhook"   # Outbound webhook record (Infrastructure → Add custom)
    yields:
      approved: "boolean"
      notes: "string"

Your notification service receives the webhook, notifies the appropriate reviewer, collects their response, and returns it.

Escalation Notifications

Set up escalation when reviews are not handled in time:

agents:
  primary_reviewer:
    name: "primary_reviewer"
    agent_type: "human"
    timeout: 300
    webhook_config:
      connection: "primary-review-webhook"
    yields:
      decision: "string"
    can_call:
      - agent: "backup_reviewer"
        condition: "decision == 'escalate'"

  backup_reviewer:
    name: "backup_reviewer"
    agent_type: "human"
    timeout: 600
    webhook_config:
      connection: "backup-review-webhook"
    yields:
      decision: "string"

When the primary reviewer escalates (or times out and the Manager routes to backup), the backup reviewer receives a notification with full context.

Notification Channels

Common integration patterns:

Channel	Integration Method
Slack	Webhook POST to Slack API
Email	SMTP via notification service
SMS	Twilio or similar API
In-app	WebSocket push to browser
PagerDuty	Event API for urgent escalations

Next Steps

Approval Workflows — Multi-step patterns
UI Integration — Review interfaces
Event System — Event reference

LeafMesh — Notification systems for human review