Webhooks

Codality receives GitHub webhook events to keep ticket state in sync and trigger agent responses.

Webhook events

Codality subscribes to these webhook events:

Event	Action	Handler
`pull_request`	`closed` (merged)	Ticket → Done, cleanup worktree, sync repo
`pull_request`	`closed` (not merged)	Ticket → Cancelled
`push`	Default branch	Sync repo, rebase all open worktrees
`check_run`	`completed` (failure)	CI feedback loop: agent auto-fix
`check_suite`	—	Logged, SSE broadcast
`issue_comment`	`created` (slash command)	Execute command (`/codality retry`, `/codality status`)
`issue_comment`	`created` (non-command)	Agent responds to comment
`pull_request_review`	`submitted` (changes_requested)	Agent addresses review feedback
`pull_request_review`	Other	Logged, SSE broadcast
`ping`	—	Responds OK (connection test)

Webhook security

Webhooks are verified using HMAC-SHA256 signatures. The GITHUB_WEBHOOK_SECRET environment variable must match the secret configured in the GitHub App.

Invalid signatures are rejected with HTTP 403.

Idempotency

Each webhook delivery has a unique delivery_id. Codality stores processed delivery IDs and skips duplicates. This prevents duplicate processing if GitHub retries a delivery.

Viewing webhook events

Go to Project → Settings → Webhooks tab to see recent webhook events for a project. Each entry shows:

Event type and action
Delivery ID
Timestamp
Processing result

Use this for debugging when expected behavior doesn't occur.

Webhook URL

The webhook endpoint is:

POST {APP_URL}/api/github/webhooks

This is configured automatically by the GitHub App manifest flow. If you move your server to a new URL, update APP_URL and reconfigure the webhook URL in your GitHub App settings.

SSE broadcast

Webhook events that affect the UI (check run results, review submissions) are broadcast via SSE to connected clients. This triggers real-time updates in the ticket detail view without polling.