Skip to main content

Documentation Index

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

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

Webhooks are in private beta. Configure them via the Sigilix dashboard (coming soon) or via the API once published.

​
Event catalog

EventWhen it fires
review.completedA review has been posted to GitHub (success or failure-fallback)
review.failedA review couldn’t run (quorum failure, internal error)
finding.createdA finding was posted (one event per finding, batched)
installation.createdSigilix was installed on a new repo
installation.deletedSigilix was uninstalled

​
Payload shape

All webhooks POST a JSON body to your endpoint with these common fields: 
{
  "event": "review.completed",
  "delivered_at": "2026-05-05T03:14:00Z",
  "delivery_id": "wh_5x8...",
  "data": {
    /* event-specific fields, see below */
  }
}
Set Content-Type: application/json and HMAC-sign with X-Sigilix-Signature: sha256=<hex> using the secret you provide at registration.

​
Per-event payloads

​
review.completed

{
  "event": "review.completed",
  "data": {
    "review_id": "rev_2y8tA9...",
    "owner": "Arc-and-Anchor",
    "repo": "sigilix",
    "pr_number": 42,
    "head_sha": "a1b2c3d4",
    "verdict": "request_changes",
    "findings_count": 4,
    "specialists_succeeded": ["glyph", "warden", "spark", "weave"],
    "rate_limit": {
      "tier": "pro",
      "used": 6,
      "max_reviews": 10,
      "resets_at": "2026-05-05T08:14:00Z"
    }
  }
}

​
finding.created

Findings are batched into a single finding.created event per review (not one event per finding). 
{
  "event": "finding.created",
  "data": {
    "review_id": "rev_2y8tA9...",
    "findings": [
      {
        "id": "fnd_4c2bX1...",
        "specialist": "warden",
        "category": "security",
        "severity": "critical",
        "path": "src/api/checkout.ts",
        "line": 142,
        "headline": "missing CSRF verification on POST /checkout"
      }
    ]
  }
}

​
review.failed

{
  "event": "review.failed",
  "data": {
    "owner": "Arc-and-Anchor",
    "repo": "sigilix",
    "pr_number": 42,
    "head_sha": "a1b2c3d4",
    "reason": "quorum_failure",
    "specialists_failed": ["warden", "spark"]
  }
}
reason values:
  • quorum_failure — fewer than the required number of specialists succeeded
  • rate_limit — review skipped due to rate limit
  • stale_head — head SHA changed during execution
  • internal_error — see telemetry for the specific error class

​
Signing

Sigilix signs every webhook with HMAC-SHA256 using the secret you provided at registration: 
X-Sigilix-Signature: sha256=<hex>
Verify in your endpoint: 
import crypto from "crypto"

function verify(body: string, signature: string, secret: string): boolean {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(body).digest("hex")
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
}
If verification fails, return 401 — Sigilix will mark the delivery failed.

​
Delivery semantics

  • Each event is delivered at-least-once to your endpoint
  • Sigilix retries on non-2xx responses with exponential backoff: 1m, 5m, 30m, 2h, 12h
  • After 5 failed retries, the delivery is marked dead-lettered and the event is dropped
  • Use the delivery_id for idempotency on your side

​
Use cases

  • Dashboards — feed reviews into your engineering metrics platform (Linear, Datadog, Honeycomb)
  • Alerting — page on-call when a Critical finding is posted on a production service
  • Compliance — log every Critical security finding to your audit trail
  • CI integration — trigger downstream jobs after a review completes (e.g., post the verdict to Slack)

Endpoints

REST API for reviews and findings.

Authentication

PAT scopes for the endpoints that webhooks reference.