External Integrations

OpenHands integrates with external services (GitHub, Slack, Jira, etc.) through webhook-based event handling:

mermaid

sequenceDiagram
    autonumber
    participant Ext as External Service
(GitHub/Slack/Jira)
    participant App as App Server
    participant IntRouter as Integration Router
    participant Manager as Integration Manager
    participant Conv as Conversation Service
    participant Sandbox as Sandbox

    Note over Ext,Sandbox: Webhook Event Flow (e.g., GitHub Issue Created)

    Ext->>App: POST /api/integration/{service}/events
    App->>IntRouter: Route to service handler
    Note over IntRouter: Verify signature (HMAC)

    IntRouter->>Manager: Parse event payload
    Note over Manager: Extract context (repo, issue, user)
    Note over Manager: Map external user → OpenHands user

    Manager->>Conv: Create conversation (with issue context)
    Conv->>Sandbox: Provision sandbox
    Sandbox-->>Conv: Ready

    Manager->>Sandbox: Start agent with task

    Note over Ext,Sandbox: Agent Works on Task...

    Sandbox-->>Manager: Task complete
    Manager->>Ext: POST result
(PR, comment, etc.)

    Note over Ext,Sandbox: Callback Flow (Agent → External Service)

    Sandbox->>App: Webhook callback
/api/v1/webhooks
    App->>Manager: Process callback
    Manager->>Ext: Update external service

Supported Integrations

Integration	Trigger Events	Agent Actions
GitHub	Issue created, PR opened, @mention	Create PR, comment, push commits
GitLab	Issue created, MR opened	Create MR, comment, push commits
Slack	@mention in channel	Reply in thread, create tasks
Jira	Issue created/updated	Update ticket, add comments
Linear	Issue created	Update status, add comments

Integration Components

Component	Purpose	Location
Integration Routes	Webhook endpoints per service	`enterprise/server/routes/integration/`
Integration Managers	Business logic per service	`enterprise/integrations/{service}/`
Token Manager	Store/retrieve OAuth tokens	`enterprise/server/auth/token_manager.py`
Callback Processor	Handle agent → service updates	`enterprise/integrations/{service}/*_callback_processor.py`

Integration Authentication

External Service (e.g., GitHub)
        │
        ▼
┌─────────────────────────────────┐
│ GitHub App Installation         │
│ - Webhook secret for signature  │
│ - App private key for API calls │
└─────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────┐
│ User Account Linking            │
│ - Keycloak user ID              │
│ - GitHub user ID                │
│ - Stored OAuth tokens           │
└─────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────┐
│ Agent Execution                 │
│ - Uses linked tokens for API    │
│ - Can push, create PRs, comment │
└─────────────────────────────────┘