Process webhook events from connected integrations with the AI Inbox -- event-driven agent automation.

AI Inbox

The AI Inbox is a unified event stream that collects webhook events from your connected integrations. Instead of polling for new emails, messages, or issues, your agents can process events as they arrive.

How It Works

Connected Integrations
  ├─ Gmail: new email received
  ├─ Slack: new message posted
  ├─ GitHub: issue opened
  └─ ...
       │
       v
  Supyagent Inbox (unified event stream)
       │
       v
  Your Agent (processes events)

Events arrive from connected providers via webhooks
Events are stored in the Supyagent inbox with a consistent format
Your agent polls the inbox or gets notified of new events
Events are processed and marked as read/archived

Inbox API

List Events

Fetch unread events from your inbox:

curl -X GET "https://app.supyagent.com/api/v1/inbox/events?status=unread&limit=20" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "data": {
    "events": [
      {
        "id": "evt_abc123",
        "provider": "google",
        "service": "gmail",
        "type": "email.received",
        "summary": "New email from alice@company.com: Q4 Budget Review",
        "payload": {
          "from": "alice@company.com",
          "subject": "Q4 Budget Review",
          "snippet": "Hi, please review the attached budget..."
        },
        "status": "unread",
        "created_at": "2025-03-15T14:30:00Z"
      },
      {
        "id": "evt_def456",
        "provider": "slack",
        "service": "messages",
        "type": "message.received",
        "summary": "Bob in #engineering: Deploy script failing on staging",
        "payload": {
          "channel": "engineering",
          "author": "Bob",
          "text": "Deploy script failing on staging -- anyone know the fix?"
        },
        "status": "unread",
        "created_at": "2025-03-15T14:25:00Z"
      }
    ],
    "total": 2,
    "next_cursor": null
  }
}

Mark Events

Mark events as read or archived:

curl -X PATCH "https://app.supyagent.com/api/v1/inbox/events/evt_abc123" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"status": "read"}'

Status values: unread, read, archived

Query Parameters

Parameter	Type	Default	Description
`status`	`str`	`"unread"`	Filter by status: `unread`, `read`, `archived`, `all`
`provider`	`str`	`null`	Filter by provider (e.g., `google`, `slack`)
`service`	`str`	`null`	Filter by service (e.g., `gmail`, `messages`)
`limit`	`int`	`20`	Maximum events to return
`cursor`	`str`	`null`	Pagination cursor

Permissions

Permission ID	Name	Type	Description
`inbox.read`	Read events	read	List and view inbox events
`inbox.write`	Manage events	write	Mark events as read or archived

Event Types

Provider	Event Type	Description
Google (Gmail)	`email.received`	New email received
Slack	`message.received`	New message in a channel or DM
GitHub	`issue.opened`	New issue created
GitHub	`issue.commented`	New comment on an issue
GitHub	`pr.opened`	New pull request created
GitHub	`pr.review`	New review on a pull request
Discord	`message.received`	New message in a channel
Notion	`page.updated`	Page content was modified

Agent Integration

Polling Pattern

The simplest approach -- your agent periodically checks the inbox:

agents/inbox_processor.yaml

name: inbox_processor
description: "Processes incoming events from the AI inbox"
type: execution

model:
  provider: anthropic/claude-sonnet-4-5-20250929

system_prompt: |
  You are an inbox processing agent. Check the inbox for unread events,
  process each one appropriately, and mark them as read.

  For emails: summarize and draft a reply if needed.
  For Slack messages: respond if it's a question directed at the team.
  For GitHub issues: triage and add labels.

service:
  enabled: true
  url: https://app.supyagent.com

Run it periodically:

# Process inbox every 5 minutes
supyagent run inbox_processor "Check the inbox for unread events and process them"

Daemon Integration

For continuous processing, use a cron job or systemd timer:

# crontab -e
*/5 * * * * cd /path/to/project && supyagent run inbox_processor "Process unread inbox events" --quiet

Or a simple loop script:

#!/bin/bash
while true; do
  supyagent run inbox_processor "Process unread inbox events" --quiet
  sleep 300  # 5 minutes
done

Multi-Agent Routing

Use delegation to route events to specialized agents:

agents/inbox_router.yaml

name: inbox_router
description: "Routes inbox events to specialized agents"
type: execution

system_prompt: |
  You are an inbox router. Check for unread events and delegate each to
  the appropriate specialized agent:
  - Email events -> delegate to email_handler
  - Slack events -> delegate to slack_responder
  - GitHub events -> delegate to github_triager

delegates:
  - email_handler
  - slack_responder
  - github_triager

Webhook Setup

Webhooks are configured automatically when you connect an integration. For some providers, additional setup may be required:

Provider	Webhook Setup
Google	Automatic via push notifications
Slack	Automatic via Events API
GitHub	Automatic via webhook registration
Discord	Automatic via Gateway events
Notion	Polling-based (Notion does not support webhooks natively)

What's Next

Connecting -- Set up integrations and API keys
API Reference -- Full REST API documentation
Execution Mode -- Automate inbox processing in CI/CD

AI Inbox

On this page