Skip to main content
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": "Sigilix",
    "repo": "sigilix",
    "pr_number": 42,
    "head_sha": "a1b2c3d4",
    "verdict": "request_changes",
    "findings_count": 4,
    "specialists_succeeded": ["logic", "security", "performance", "tests"],
    "rate_limit": {
      "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": "security",
        "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": "Sigilix",
    "repo": "sigilix",
    "pr_number": 42,
    "head_sha": "a1b2c3d4",
    "reason": "quorum_failure",
    "specialists_failed": ["security", "performance"]
  }
}
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.