Cadence logoCadencev0.2.1
Docs/Webhook Server

Webhook Server

Run Cadence as an HTTP server that receives Git push events and analyzes repositories continuously

The Cadence webhook server is a long-running HTTP process that receives push events from GitHub or GitLab, queues analysis jobs, and exposes results via REST or Server-Sent Events (SSE).

How It Works

When a push event arrives, the server:

  1. Validates the webhook signature (HMAC-SHA256 for GitHub, token header for GitLab)
  2. Enqueues an analysis job
  3. Clones the repository to a temporary directory (2-minute timeout)
  4. Runs all enabled detection strategies
  5. Computes metrics and suspicion scores
  6. Stores the result in the job queue

Results are accessible immediately via GET /jobs/:id once the job completes. Jobs persist for the lifetime of the process (no disk persistence between restarts).

Starting the Server

Bash
cadence webhook [flags]
FlagDefaultDescription
--port8000HTTP listen port
--host0.0.0.0Bind address
--secret—Webhook HMAC secret (GitHub)
--workers4Concurrent analysis workers
--timeout30sPer-request timeout

Minimal Example

Bash
cadence webhook --port 8000 --secret "my-secret"

With AI Skills Enabled

Bash
export CADENCE_AI_ENABLED=true
export CADENCE_AI_PROVIDER=openai
export CADENCE_AI_KEY=sk-...

cadence webhook --port 8000 --secret "my-secret"

API Surface

The webhook server registers the following endpoints:

EndpointMethodPurpose
/webhooks/githubPOSTReceive GitHub push events
/webhooks/gitlabPOSTReceive GitLab push events
/api/analyze/repositoryPOSTOn-demand repository analysis
/api/analyze/websitePOSTOn-demand website analysis
/api/stream/repositoryPOSTSSE streaming repository analysis
/api/stream/websitePOSTSSE streaming website analysis
/jobs/:idGETGet job status and results
/jobsGETList recent jobs (up to 50)
/api/results/:idGETGet job result only
/metricsGETPrometheus-compatible metrics
/api/metricsGETMetrics as JSON
/api/cache/statsGETCache statistics
/api/cache/clearPOSTClear analysis result cache
/api/pluginsGETList loaded analysis plugins
/healthGETHealth check

Full endpoint documentation: API Reference

Platform Setup

Job Lifecycle

Jobs follow this state machine:

queued → running → completed
                → failed

Poll GET /jobs/:id until status is completed or failed.

Bash
# Submit a job
curl -X POST http://localhost:8000/api/analyze/repository \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com/owner/repo", "branch": "main"}'
# → {"job_id": "abc123", "status": "queued"}

# Poll for result
curl http://localhost:8000/jobs/abc123
# → {"status": "completed", "result": {...}}

Or use SSE to receive results as they stream in:

Bash
curl -N -X POST http://localhost:8000/api/stream/repository \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com/owner/repo"}'

Health Check

Bash
curl http://localhost:8000/health
# → {"status": "ok"}
BackHome