API & Webhook Endpoints

The agent services expose webhook endpoints for receiving events from Slack, Jira, and GitHub, plus API endpoints for session pods and the dashboard.

Note

Webhook handlers are shared across all agents via the platform layer (internal/platform/webhook/). Events are published to NATS subjects in the format webhooks.{agent}.{type}, where agent is buck, dolly, or pearl and type is slack, slack_interaction, jira, session-update, github_comment, or dashboard_message. Each agent runs its own NATS consumer that pulls only from its namespace.

Endpoint reference

Webhooks

Endpoint	Method	Auth	Purpose
/healthz	GET	None	Health check
/webhooks/slack/events	POST	HMAC-SHA256	Slack Events API (app_mention, thread replies)
/webhooks/slack/interactivity	POST	HMAC-SHA256	Block Kit interaction callbacks
/webhooks/jira	POST	Webhook secret	Jira ticket assignments and comments
/webhooks/github	POST	HMAC-SHA256	GitHub App webhooks (@bucky on issues)

Runner API (session pods)

Endpoint	Method	Auth	Purpose
/api/runner/sessions/{id}	GET	Pod JWT	Session context for pod startup
/api/runner/sessions/{id}/complete	POST	Pod JWT	Session outcome delivery from pods
/api/runner/sessions/{id}/pause	POST	Pod JWT	Session pause notification from pods
/api/upload	POST	OIDC JWT or Pod JWT	File uploads from Claude runners

Dashboard API

Endpoint	Method	Auth	Purpose
/api/dashboard/*	Various	Okta JWT	Connect RPC endpoints for the web dashboard
/api/sessions/{id}/events	GET	Okta JWT	SSE stream for real-time pod status updates
/ws/sessions/{id}/attach	GET	Okta JWT	WebSocket tunnel for interactive terminal access

Slack events (/webhooks/slack/events)

Handles app_mention events and thread replies. Signature verification uses HMAC-SHA256 with the agent’s SLACK_SIGNING_SECRET.

Deduplication: By Slack event ID — duplicate deliveries are ignored. Deduplication is per-agent, so the same event ID processed by different agents does not conflict.

Processing: Returns 200 immediately, publishes to webhooks.{agent}.slack on NATS. The agent’s consumer picks up the event and processes it asynchronously. Extracts images from Files on each message (JPEG, PNG, GIF, WebP) and downloads them via bot token auth.

Slack interactivity (/webhooks/slack/interactivity)

Handles Block Kit interaction callbacks (button clicks, select choices, date picks). Payloads arrive as application/x-www-form-urlencoded with a payload JSON field.

The handler:

1. Verifies HMAC-SHA256 signature
2. Extracts the user’s action
3. Formats a human-readable summary
4. Routes it to the ADK agent session for the thread

Jira webhooks (/webhooks/jira)

A single endpoint handles both ticket assignments and comments. The handler inspects the webhookEvent field to determine the event type:

• Assignment: Creates a new session and starts processing
• Comment: Routes to the existing session for the ticket via the session index

The endpoint:

• Authenticates via webhook secret (per-agent: JIRA_WEBHOOK_SECRET, DOLLY_JIRA_WEBHOOK_SECRET, PEARL_JIRA_WEBHOOK_SECRET)
• Filters out self-comments (from the agent’s own Jira account)
• Uses {agent}:jira:{issueKey} session index keys for continuity

GitHub webhooks (/webhooks/github)

Handles issue_comment events with @bucky mentions on issues and PRs.

• Auth: HMAC-SHA256 signature verification with GITHUB_WEBHOOK_SECRET
• Dedup: By comment ID (per-agent)
• Session key: buck:github:{owner/repo}#{number}

Caution

GitHub webhook handling requires GITHUB_WEBHOOK_SECRET to be configured. Without it, the endpoint is disabled.

Runner API

The runner API handles communication between EKS session pods and the agent.

Session context (/api/runner/sessions/{id})

Pods call this at startup to fetch the session prompt, instructions, and configuration.

Authentication: Pod-bound JWT (HMAC-signed) generated by the agent when creating the pod.

Session complete (/api/runner/sessions/{id}/complete)

Receives session outcome reports from pods when Claude finishes.

Authentication: Pod-bound JWT.

Payload includes: status, artifacts (comments, PRs, labels), and the final assistant message. The handler looks up the pending session, injects results as a new user message, and the agent resumes reasoning.

Session pause (/api/runner/sessions/{id}/pause)

Receives pause notifications from pods. The pod has already saved state to S3 via save-state.sh. The handler records the state_key, scrollback_key, and last_assistant_message on the session.

File upload (/api/upload)

Endpoint for Claude Code runners to upload files (screenshots, artifacts).

Authentication: OIDC JWT (GitHub Actions) or pod-bound JWT (EKS pods).

• Returns permanent CloudFront URLs when CLOUDFRONT_DOMAIN is configured
• Falls back to pre-signed S3 GET URLs (7-day TTL)

Dashboard API

Connect RPC (/api/dashboard/*)

The web dashboard communicates with the agent via Connect RPC endpoints. Proto definitions live in agent/proto/api/v1/dashboard_service.proto. Key RPCs include session CRUD, metrics queries, team settings, and session management (pause, resume, terminate).

Authentication: Okta OIDC JWT validated via the OKTA_ISSUER JWKS endpoint.

SSE events (/api/sessions/{id}/events)

Server-sent events stream for real-time pod status updates. The dashboard subscribes to this endpoint to show live status changes (pending, running, succeeded, failed) and pod name assignments.

WebSocket terminal tunnel (/ws/sessions/{id}/attach)

Upgrades to a WebSocket connection that proxies stdin/stdout to the pod’s tmux session via Kubernetes exec. Enables interactive terminal access from the dashboard while a session is running.