Claude Webhook API Documentation

Overview

The Claude Webhook API provides endpoints for creating and managing Claude Code sessions for automated code generation, analysis, and orchestration. This API is designed to enable parallel execution of multiple Claude instances for complex software engineering tasks.

API Design Philosophy

This API follows a simple, focused design:

• Single responsibility: Each session handles one specific task
• Orchestration via MCP/LLM agents: Complex workflows are managed by the calling agent, not the API
• Consistent response format: All responses follow the same structure for predictable parsing

Base Configuration

Base URL

POST https://your-domain.com/api/webhooks/claude

Authentication

All requests require Bearer token authentication:

Authorization: Bearer <CLAUDE_WEBHOOK_SECRET>
Content-Type: application/json

Response Format

All API responses follow this consistent structure:

{
  "success": boolean,
  "message": "string",     // Human-readable status message
  "data": object,          // Response data (when success=true)
  "error": "string"        // Error description (when success=false)
}

Rate Limiting

• Currently not implemented (planned for future release)
• Recommended client-side rate limiting: 10 requests per minute

Endpoints

1. Create Session

Creates a new Claude Code session. Sessions can be configured with dependencies, metadata, and execution options.

Endpoint: POST /api/webhooks/claude
Type: session.create

Request Body

{
  "type": "session.create",
  "session": {
    "type": "implementation | analysis | testing | review | coordination",
    "project": {
      "repository": "string",      // Required: "owner/repo" format
      "branch": "string",          // Optional: target branch
      "requirements": "string",    // Required: task description
      "context": "string"          // Optional: additional context
    },
    "dependencies": ["string"],    // Optional: array of session IDs to wait for
    "metadata": {                  // Optional: custom metadata
      "batchId": "string",         // Group related sessions
      "tags": ["string"],          // Categorization tags
      "priority": "string"         // Priority level
    }
  },
  "options": {                     // Optional: execution options
    "autoStart": boolean,          // Start when dependencies complete (default: false)
    "timeout": number,             // Custom timeout in seconds (default: 1800)
    "notifyUrl": "string"          // Webhook URL for completion notification
  }
}

Parameters

Response

{
  "success": true,
  "message": "Session created successfully",
  "data": {
    "session": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "implementation",
      "status": "pending",
      "project": {
        "repository": "acme/webapp",
        "branch": "feature/user-auth",
        "requirements": "Implement JWT authentication middleware",
        "context": "Use existing User model"
      },
      "dependencies": [],
      "metadata": {
        "batchId": "auth-feature-batch",
        "tags": ["feature", "auth"],
        "priority": "high"
      },
      "options": {
        "autoStart": false,
        "timeout": 1800,
        "notifyUrl": null
      },
      "containerId": null,
      "claudeSessionId": null,
      "createdAt": "2024-01-06T10:00:00Z",
      "startedAt": null,
      "completedAt": null,
      "output": null,
      "error": null
    }
  }
}

Example

curl -X POST https://your-domain.com/api/webhooks/claude \\
  -H "Authorization: Bearer your-secret-token" \\
  -H "Content-Type: application/json" \\
  -d '{
    "type": "session.create",
    "session": {
      "type": "implementation",
      "project": {
        "repository": "acme/webapp",
        "branch": "feature/user-auth",
        "requirements": "Implement JWT authentication middleware for Express.js",
        "context": "Use existing User model and bcrypt for password hashing"
      },
      "dependencies": []
    }
  }'

---

2. Start Session

Starts a previously created session or queues it if dependencies aren't met.

Endpoint: POST /api/webhooks/claude
Type: session.start

Request Body

{
  "type": "session.start",
  "sessionId": "string"
}

Parameters

Response

{
  "success": true,
  "message": "Session started successfully",
  "data": {
    "session": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "initializing",  // or "running" if started immediately
      "containerId": "docker-container-id",
      "claudeSessionId": "claude-internal-session-id",
      // ... full session object
    }
  }
}

For queued sessions (waiting on dependencies):

{
  "success": true,
  "message": "Session queued",
  "data": {
    "session": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "pending",
      // ... full session object
    },
    "queueStatus": {
      "waitingFor": ["dependency-session-id-1", "dependency-session-id-2"],
      "estimatedStartTime": null
    }
  }
}

Example

curl -X POST https://your-domain.com/api/webhooks/claude \\
  -H "Authorization: Bearer your-secret-token" \\
  -H "Content-Type: application/json" \\
  -d '{
    "type": "session.start",
    "sessionId": "550e8400-e29b-41d4-a716-446655440000"
  }'

---

3. Get Session Status

Retrieves the current status and details of a session.

Endpoint: POST /api/webhooks/claude
Type: session.get

Request Body

{
  "type": "session.get",
  "sessionId": "string"
}

Parameters

Response

{
  "success": true,
  "message": "Session found",
  "data": {
    "session": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "implementation",
      "status": "running",
      "containerId": "docker-container-id",
      "claudeSessionId": "claude-internal-session-id",
      "project": {
        "repository": "acme/webapp",
        "branch": "feature/user-auth",
        "requirements": "Implement JWT authentication middleware",
        "context": "Use existing User model"
      },
      "dependencies": [],
      "metadata": {},
      "options": {},
      "createdAt": "2024-01-06T10:00:00Z",
      "startedAt": "2024-01-06T10:30:00Z",
      "completedAt": null,
      "output": null,
      "error": null
    }
  }
}

Session Status Values

• pending - Session created but not started
• initializing - Container is being created
• running - Session is actively executing
• completed - Session finished successfully
• failed - Session encountered an error
• cancelled - Session was manually cancelled

---

4. Get Session Output

Retrieves the output and artifacts from a completed session.

Endpoint: POST /api/webhooks/claude
Type: session.output

Request Body

{
  "type": "session.output",
  "sessionId": "string"
}

Parameters

Response

{
  "success": true,
  "message": "Session output retrieved",
  "data": {
    "output": {
      "logs": ["Container started", "Running Claude command...", "Task completed"],
      "artifacts": [
        {
          "type": "file",
          "path": "src/middleware/auth.js",
          "content": "// JWT authentication middleware\
...",
          "sha": "abc123...",
          "url": "https://github.com/acme/webapp/blob/feature/user-auth/src/middleware/auth.js",
          "metadata": {
            "linesAdded": 150,
            "linesRemoved": 0
          }
        }
      ],
      "summary": "Implemented JWT authentication middleware with refresh token support",
      "nextSteps": ["Add rate limiting", "Implement password reset flow"],
      "executionTime": 180,  // seconds
      "resourceUsage": {
        "cpuTime": 45.2,
        "memoryPeak": "512MB"
      }
    }
  }
}

Note: The current implementation returns a simplified structure. Full artifact details and metadata are planned for future releases.

---

5. List Sessions

Lists all sessions, optionally filtered by orchestration ID.

Endpoint: POST /api/webhooks/claude
Type: session.list

Request Body

{
  "type": "session.list",
  "orchestrationId": "string"  // Optional
}

Parameters

Response

{
  "success": true,
  "message": "Sessions retrieved",
  "data": {
    "sessions": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "type": "implementation",
        "status": "completed",
        "project": {
          "repository": "acme/webapp",
          "branch": "feature/user-auth",
          "requirements": "Implement JWT authentication",
          "context": null
        },
        "dependencies": [],
        "metadata": {
          "batchId": "auth-feature-batch",
          "tags": ["feature", "auth"]
        },
        "createdAt": "2024-01-06T10:00:00Z",
        "startedAt": "2024-01-06T10:30:00Z",
        "completedAt": "2024-01-06T10:45:00Z",
        "error": null
      },
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "type": "testing",
        "status": "running",
        "project": {
          "repository": "acme/webapp",
          "branch": "feature/user-auth",
          "requirements": "Write tests for JWT middleware"
        },
        "dependencies": ["550e8400-e29b-41d4-a716-446655440000"],
        "metadata": {
          "batchId": "auth-feature-batch",
          "tags": ["testing"]
        },
        "createdAt": "2024-01-06T10:46:00Z",
        "startedAt": "2024-01-06T10:47:00Z",
        "completedAt": null,
        "error": null
      }
    ]
  }
}

Session Types

implementation

For implementing new features or functionality. Claude will:

• Analyze requirements
• Write production-ready code
• Follow existing patterns and conventions
• Create or modify files as needed

analysis

For analyzing existing code. Claude will:

• Review code structure and patterns
• Identify potential issues
• Suggest improvements
• Document findings

testing

For creating and running tests. Claude will:

• Write unit and integration tests
• Ensure code coverage
• Validate functionality
• Fix failing tests

review

For code review tasks. Claude will:

• Review pull requests
• Check for security issues
• Validate best practices
• Provide feedback

coordination

For orchestrating multiple sessions. Claude will:

• Break down complex tasks
• Create dependent sessions
• Monitor progress
• Coordinate results

Dependency Management

Sessions can depend on other sessions using the dependencies parameter:

{
  "type": "session.create",
  "session": {
    "type": "testing",
    "project": {
      "repository": "acme/webapp",
      "requirements": "Write tests for the JWT authentication middleware"
    },
    "dependencies": ["implementation-session-id"]
  }
}

Dependency Behavior

• Sessions with dependencies won't start until all dependencies are completed
• If any dependency fails, the dependent session will be marked as failed
• Circular dependencies are detected and rejected
• Maximum dependency depth is 10 levels

Error Handling

Error Response Format

{
  "success": false,
  "error": "Error description"
}

Common Error Codes

• 400 - Bad Request (invalid parameters)
• 401 - Unauthorized (invalid token)
• 404 - Not Found (session doesn't exist)
• 409 - Conflict (session already started)
• 429 - Too Many Requests (rate limit exceeded)
• 500 - Internal Server Error

Example Error Response

{
  "success": false,
  "error": "Session not found: 550e8400-e29b-41d4-a716-446655440000"
}

Best Practices

1. Clear Requirements

Provide detailed, actionable requirements:

{
  "requirements": "Implement JWT authentication middleware with:\
- Access token (15min expiry)\
- Refresh token (7 days expiry)\
- Token blacklisting for logout\
- Rate limiting per user"
}

2. Use Dependencies Wisely

Chain related tasks:

analysis → implementation → testing → review

3. Provide Context

Include relevant context about your codebase:

{
  "context": "We use Express.js with TypeScript, Prisma ORM, and follow REST API conventions. Authentication should integrate with existing User model."
}

4. Monitor Session Status

Poll session status every 5-10 seconds:

while [ "$status" != "completed" ]; do
  status=$(curl -s -X PO