Codexa
Back to Docs

Reference

Webhook events

What Codexa listens for, how it verifies requests, and what triggers a review.

Endpoint

POST /webhooks/github

Verification

Every webhook is verified using HMAC-SHA256. The signature in the X-Hub-Signature-256 header is compared against an HMAC of the raw request body using your GITHUB_WEBHOOK_SECRET. Mismatched requests return 401 without doing any work — protecting the AI quota and database from spam.

Events Codexa subscribes to

Only pull_request events trigger a review. The bot responds to four actions:

  • opened — first review on a brand-new PR
  • reopened — re-review when a closed PR comes back
  • synchronize — re-review on every new commit pushed to the PR
  • ready_for_review — when a draft PR is marked ready

All other actions (assigned, labeled, edited, etc.) and all other events are ignored with a 200 OK + {ok: true, ignored: <event>}.

ℹ️ Draft PRs are skipped
If pull_request.draft is true, no review fires. Convert the PR to ready-for-review to trigger Codexa.

Lifecycle of a review

1. GitHub sends pull_request webhook
2. /webhooks/github verifies HMAC signature      → 401 on mismatch
3. Insert "pending" review row in Supabase       → dashboard shows activity
4. Return 200 OK to GitHub immediately           → ack within ~50ms
5. Background task: fetch PR diff via REST API
6. Background task: create "in_progress" check run on the PR head SHA
7. Background task: AIRouter calls Gemini → falls back to Groq on failure
8. Background task: filter findings by per-repo severity threshold
9. Background task: render Markdown comment + post via /issues/comments
10. Background task: update check run with success/failure conclusion
11. Background task: update Supabase row to "completed" with findings JSON

Total time: typically 6–12 seconds, rarely > 20s. The webhook itself returns within ~50ms because all the work is offloaded to a FastAPI background task.

Failure modes

  • Diff fetch fails — typically a transient GitHub API issue. Review marked failed; check run marked neutral with a friendly message.
  • All AI providers exhausted — both Gemini and Groq returned 429 or errored. Review marked failed with the last error in the row.
  • Comment post fails — installation token expired mid-flight, or GitHub API hiccup. Review row keeps the AI summary and findings (so the dashboard still shows them) but is marked failed.

Skipping a review

Two ways:

  • Open the PR as a draft — no review fires until you mark it ready
  • Disable Codexa for the repo in /dashboard/settings/repos/{repo}