Webhook Endpoints

The agent service exposes several webhook endpoints for receiving events from Slack, Jira, GitHub, and workflow callbacks.

Endpoint reference

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
/webhooks/jira/comments	POST	Webhook secret	Jira ticket comments
/webhooks/github	POST	HMAC-SHA256	GitHub App webhooks (@bucky on issues)
/webhooks/workflow-callback	POST	OIDC JWT	Session outcome delivery from workflows
/api/upload	POST	OIDC JWT	File uploads from Claude runners

Slack events (/webhooks/slack/events)

Handles app_mention events and thread replies. Signature verification uses HMAC-SHA256 with SLACK_SIGNING_SECRET.

Deduplication: By Slack event ID — duplicate deliveries are ignored.

Processing: Returns 200 immediately, processes asynchronously via worker pool. 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 — Handles ticket assignments. When a ticket is assigned to Bucky, creates a new session and starts processing.

/webhooks/jira/comments — Handles comments on tickets. Routes to the existing session for the ticket via the session index.

Both endpoints:

• Share the same webhook secret authentication
• Filter out self-comments (from Bucky’s own Jira account)
• Use jira:<issueKey> session index keys

GitHub webhooks (/webhooks/github)

Handles issue_comment events with @bucky mentions on issues only. PR comments are ignored (handled by tag-bucky in GitHub Actions).

• Auth: HMAC-SHA256 signature verification with GITHUB_WEBHOOK_SECRET
• Dedup: By comment ID
• Session key: github:<owner/repo>#<number>

Caution

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

Workflow callback (/webhooks/workflow-callback)

Receives session outcome reports from the report-session-outcome action.

Authentication: GitHub Actions OIDC JWT validated against GitHub’s public JWKS with:

• Issuer check (https://token.actions.githubusercontent.com)
• Audience check (callback URL)
• repository_owner claim check

Payload:

{
  "session_id": "uuid",
  "status": "success|failure|cancelled",
  "mode": "",
  "repo": "owner/repo",
  "issue_number": 42,
  "run_url": "https://github.com/...",
  "artifacts": [
    { "type": "comment", "body": "..." },
    { "type": "pull_request", "url": "...", "number": 43 },
    { "type": "label", "name": "needs-review" }
  ]
}

The handler looks up the pending session, injects results as a new user message, and the agent resumes reasoning.

File upload (/api/upload)

OIDC-authenticated endpoint for Claude Code runners to upload files (screenshots, artifacts).

• Returns permanent CloudFront URLs when CLOUDFRONT_DOMAIN is configured
• Falls back to pre-signed S3 GET URLs (7-day TTL)
• The FILE_UPLOAD_URL environment variable is set in dispatch workflows so runners know where to upload