--- title: "Claude Webhook API Documentation" description: "**Endpoint:** `POST /api/webhooks/claude` **Type:** `session.create`" type: skill canonical_url: https://claudary.paisolsolutions.com/skills/claude-webhook-api source: "Claudary" difficulty: intermediate author: "Claude Code Knowledge Pack" date: 2026-07-10T11:13:58.598Z license: CC-BY-4.0 attribution: "Claude Webhook API Documentation — Claudary (https://claudary.paisolsolutions.com/skills/claude-webhook-api)" --- # Claude Webhook API Documentation **Endpoint:** `POST /api/webhooks/claude` **Type:** `session.create` ## Overview # 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: ```http Authorization: Bearer Content-Type: application/json ``` ### Response Format All API responses follow this consistent structure: ```json { "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 ```json { "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 | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `type` | string | Yes | Must be "session.create" | | `session` | object | Yes | Session configuration object | | `session.type` | string | Yes | Type of session: `implementation`, `analysis`, `testing`, `review`, or `coordination` | | `session.project` | object | Yes | Project information | | `session.project.repository` | string | Yes | GitHub repository in "owner/repo" format | | `session.project.branch` | string | No | Target branch name (defaults to main/master) | | `session.project.requirements` | string | Yes | Clear description of what Claude should do | | `session.project.context` | string | No | Additional context about the codebase or requirements | | `session.dependencies` | string[] | No | Array of valid UUID session IDs that must complete before this session starts (filters out "none", empty strings) | | `session.metadata` | object | No | Custom metadata for organizing sessions | | `session.metadata.batchId` | string | No | User-provided ID for grouping related sessions | | `session.metadata.tags` | string[] | No | Tags for categorization | | `session.metadata.priority` | string | No | Priority level (high, medium, low) | | `options` | object | No | Execution options | | `options.autoStart` | boolean | No | Automatically start when dependencies complete (default: false) | | `options.timeout` | number | No | Custom timeout in seconds (default: 1800 = 30 minutes) | | `options.notifyUrl` | string | No | Webhook URL to call on completion/failure | #### Response ```json { "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 ```bash 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 ```json { "type": "session.start", "sessionId": "string" } ``` #### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `type` | string | Yes | Must be "session.start" | | `sessionId` | string | Yes | UUID of the session to start | #### Response ```json { "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): ```json { "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 ```bash 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 ```json { "type": "session.get", "sessionId": "string" } ``` #### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `type` | string | Yes | Must be "session.get" | | `sessionId` | string | Yes | UUID of the session to query | #### Response ```json { "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 ```json { "type": "session.output", "sessionId": "string" } ``` #### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `type` | string | Yes | Must be "session.output" | | `sessionId` | string | Yes | UUID of the session | #### Response ```json { "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\\n...", "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 ```json { "type": "session.list", "orchestrationId": "string" // Optional } ``` #### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `type` | string | Yes | Must be "session.list" | | `orchestrationId` | string | No | Filter sessions by orchestration ID | #### Response ```json { "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: ```json { "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 ```json { "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 ```json { "success": false, "error": "Session not found: 550e8400-e29b-41d4-a716-446655440000" } ``` ## Best Practices ### 1. Clear Requirements Provide detailed, actionable requirements: ```json { "requirements": "Implement JWT authentication middleware with:\\n- Access token (15min expiry)\\n- Refresh token (7 days expiry)\\n- Token blacklisting for logout\\n- Rate limiting per user" } ``` ### 2. Use Dependencies Wisely Chain related tasks: ``` analysis → implementation → testing → review ``` ### 3. Provide Context Include relevant context about your codebase: ```json { "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: ```bash while [ "$status" != "completed" ]; do status=$(curl -s -X PO --- Source: [Claudary](https://claudary.paisolsolutions.com/skills/claude-webhook-api) · https://claudary.paisolsolutions.com