Qodo webhook server

Documentation Index

Fetch the complete documentation index at: https://docs.qodo.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

• Purpose: Turn your agent commands into HTTP endpoints. Each command becomes a POST /webhook/.
• Modes of use:
  • One‑shot request: POST and wait for the final JSON response
  • Two‑step streaming: POST to start, then connect to an SSE stream to receive incremental updates until completion
• Typical use cases: Integrations with your CI/CD, backend workflows, or any external systems that want to trigger agents programmatically.

​

Prerequisites

• QODO_API_KEY must be set and valid for your environment.
• A valid agent configuration file (agent.toml/agent.yaml/agent.yml) must be available in the current working directory or parent directories.

​

Start the server

• Command:
  • qodo --webhook
  • Optional port override: qodo --webhook -p 6666
• Default port: 6666. The server will search for the first available port at or above the requested port.
• Exposed commands:
  • By default, every command in your agent config is exposed at /webhook/{commandName}.
  • If you start Qodo targeting a specific command or use a single‑command agent file, only that command is exposed.
• Shutdown:
  • Press ESC or Ctrl+C to exit.

​

Endpoints

​

1) POST /webhook/

• Query parameters:
  • sse (boolean): If present and truthy, the server returns { sessionId } immediately, and you then connect to SSE (see below).
  • stream (boolean): Optional; streaming is effectively enabled whenever sse is provided.
  • sessionId (string): Optional; reuse an existing session (also supported as an X-Session-ID header). If omitted, the server generates a new sessionId.
• Headers:
  • X-Session-ID (optional on request): Reuse an existing session.
  • X-Session-ID (always on response): The sessionId used for this request.
• Request body (JSON):
  • Fields must match your command’s arguments definition in the agent config. Invalid payloads return a 400 status code with validation errors.
• Responses:
  • 200 (non‑SSE): Final JSON result. If your agent emits structured output, that JSON is returned; otherwise { "result": "<final text>" }.
  • 200 (SSE mode): { "sessionId": "<id>" } so you can open an SSE stream.
  • 400: Invalid payload → { error: string, details?: any[] }
  • 500: Internal error (includes a readable message when possible)

​

2) GET /webhook/?sessionId=…

• Query parameters:
  • sessionId (required): The sessionId returned by the POST call.
• SSE events:
  • event: message data: { "content": string } – incremental agent messages
  • event: error data: { "error": string } – error messages
  • event: loading data: { "isLoading": boolean } – task activity flag
  • event: done data: {} – sent right before the stream closes (completion)
• Errors:
  • 400: missing/invalid sessionId
  • 404: unknown commandName or sessionId

​

Request validation

• Supported types: string, number, boolean, array, object
• Required by default unless a field has required: false
• Defaults and enums (if provided) are applied/validated
• On validation error: HTTP 400 with details

​

Sessions and lifecycle

• Session assignment:
  • Provide X-Session-ID header or ?sessionId= to reuse an existing session.
  • If omitted, the server obtains a fresh sessionId from the backend and returns it.
• Session storage:
  • Each session is backed by an internal message manager that tracks AI messages, error state, and loading state.
• Cleanup & TTL:
  • Non‑SSE: the session is cleaned up after the response is sent.
  • SSE: the session is cleaned up when loading=false (you’ll receive a final done event) or if the client disconnects.
  • Periodic cleanup removes sessions older than 90 minutes. Cleanup runs every 5 minutes.
• Timeout (non‑SSE only):
  • The synchronous POST request has a 90-minute timeout and returns a 500 error if exceeded.

​

Continue an existing session

• Include X-Session-ID: <SESSION_ID> on the POST /webhook/{commandName} request. The server will reuse that session and its context/history.
• For streaming:
  1. Start the task with POST /webhook/{commandName}?sse=true and the same X-Session-ID header (or pass sessionId=<SESSION_ID> in the query).
  2. Connect to GET /webhook/{commandName}?sessionId=<SESSION_ID> to receive events.

​

Example

• Arguments:
  • pr (string, optional): URL of the pull request to analyze (recommended when using webhook mode).
• Output (structured):
  • An object with summary and findings[].
  • Each finding includes: finding_title, severity_level (“breaking-issue” | “concern”), repo_name, file_path, reason, diff_pointer, recommended_fix, and evidence.
  • diff_pointer shape (as defined in the command’s schema) includes: start_line, end_line, and hunk_header.

​

A) One‑shot (no streaming)

curl -X POST "http://localhost:6666/webhook/review" \
  -H "Content-Type: application/json" \
  -d '{ "pr": "https://github.com/org/repo/pull/123" }'

{
  "summary": "Analyzed PR #123 – identified 2 issues likely to break runtime behavior.",
  "findings": [
    {
      "finding_title": "Null check removed in foo()",
      "severity_level": "breaking-issue",
      "repo_name": "org/repo",
      "file_path": "src/foo.ts",
      "reason": "Removal of null guard introduces potential null dereference at runtime.",
      "diff_pointer": {
        "start_line": 120,
        "end_line": 130,
        "hunk_header": "@@ -118,6 +120,12 @@"
      },
      "recommended_fix": "Restore the null check before accessing the value; add a unit test to cover null inputs.",
      "evidence": "Before: value was checked for null; After: direct access without guard. This path is reachable when config is missing."
    }
  ]
}

​

B) Two‑step with SSE

curl -s -X POST "http://localhost:6666/webhook/review?sse=true" \
  -H "Content-Type: application/json" \
  -d '{ "pr": "https://github.com/org/repo/pull/123" }'
# => { "sessionId": "<SESSION_ID>" }

curl -N "http://localhost:6666/webhook/review?sessionId=<SESSION_ID>"

event: loading
data: {"isLoading":true}

event: message
data: {"content":"Analyzing PR #123..."}

event: message
data: {"content":"Found 2 potential issues"}

event: loading
data: {"isLoading":false}

event: done
data: {}

​

C) Reusing a session

curl -X POST "http://localhost:6666/webhook/review" \
  -H "X-Session-ID: <EXISTING_SESSION>" \
  -H "Content-Type: application/json" \
  -d '{ "pr": "https://github.com/org/repo/pull/456" }'

​

Options and flags that influence behavior

• --webhook – start the webhook server
• -p, --port – set the starting port (default: 6666)
• Tool selection:
  • --tool <name> (repeatable) or --tools=name1,name2
  • --no-tool <server.tool> (repeatable) or --no-tools=server.tool1,server.tool2
• Permissions:
  • --permissions <r|rw|rwx|-> to override command permissions

​

Security considerations

• The server does not enforce HTTP authentication. Treat it as a development/local service or place it behind your API gateway/reverse proxy that handles auth and TLS.
• Ensure QODO_API_KEY is set appropriately and that you don’t expose this server publicly without protections.

​

Troubleshooting

• 400 Invalid Payload:
  • Ensure your request body matches the command’s arguments definition (for review, the optional pr string).
• 404 Not Found:
  • Check the commandName path, and ensure sessionId is valid for SSE.
• 500 Internal Error / Timeout:
  • Non‑SSE POST requests time out after 90 minutes. Use SSE for long‑running tasks.
• No output / empty result:
  • If the agent produced no messages, the non‑SSE response falls back to { "result": "No response" }.

​

Notes

• Requests are executed in a non‑interactive, webhook‑friendly manner. Do not expect to receive user prompts or approvals through this interface.
• For long-running operations and real-time visibility into progress, prefer the two-step SSE pattern.