Event Ingestion

Syntropic137 uses a hybrid approach to receive GitHub events from three sources: webhooks for real-time delivery, Events API polling for zero-config event ingestion, and Checks API polling for CI failure detection (self-healing). All three feed into a unified pipeline with content-based deduplication: the same event is never processed twice, regardless of how it arrives.

How It Works

1. Webhook endpoint receives GitHub webhook deliveries in real time (~1s)
2. Events API poller runs as a background task, polling GitHub's Events API for repositories that have active triggers (17 event types including PR, push, etc.)
3. Checks API poller watches commit SHAs from PR events and polls GET /repos/{owner}/{repo}/commits/{sha}/check-runs to detect CI failures, enabling self-healing without webhooks (~30-90s latency)
4. All three sources normalize their payloads into a common NormalizedEvent format
5. The EventPipeline checks each event against a dedup store (Redis) using content-based keys: if the event was already processed, it's skipped
6. New events are routed to trigger evaluation, which fires matching workflows

Polling Modes

The poller adapts its behavior based on whether webhooks are arriving:

When you first start Syntropic137 without a webhook URL configured, the poller operates in Active Polling mode, checking for new events every 60 seconds. Once webhooks start arriving (after configuring a tunnel or public URL), the poller automatically backs off to Safety Net mode, polling every 5 minutes as a catch-up mechanism.

If webhooks stop arriving (tunnel goes down, GitHub outage), the poller detects the gap after 30 minutes and switches back to active polling.

Checks API Polling (Self-Healing)

The Checks API poller enables zero-config self-healing: detecting CI failures without requiring a webhook URL or tunnel setup.

How it works:

1. When a pull_request event arrives (from either the Events API poller or webhooks), the pipeline registers the PR's head commit SHA
2. The Checks API poller periodically calls GET /repos/{owner}/{repo}/commits/{sha}/check-runs for each registered SHA
3. When a check run completes with conclusion: failure, the poller synthesizes a check_run.completed event identical to what a webhook would deliver
4. The synthesized event flows through the same EventPipeline.ingest() path, triggering self-healing workflows

The poller only runs when at least one active trigger listens for check_run events. SHAs are automatically cleaned up after all check runs complete or after a 2-hour TTL (for abandoned PRs).

Deduplication

When both webhooks and polling are active, the same event may arrive from both sources. Syntropic137 prevents double-processing using content-based dedup keys.

Each event type has a dedicated key extractor that uses stable identifiers present in both webhook and Events API payloads:

• Push events: repository + commit SHA (after field)
• Pull requests: repository + PR number + action + updated_at timestamp
• Check runs: repository + check run ID + action
• Issue comments: repository + comment ID + action

Keys are stored in Redis with a 24-hour TTL using atomic SETNX: the first source to deliver an event "wins," and the duplicate from the other source is silently skipped.

Fail-open behavior

If Redis is temporarily unavailable, events are processed anyway rather than dropped. Trigger safety guards (fire counts, cooldown periods) provide second-layer protection against duplicate workflows.

GitHub API Quota

The Events API has a rate limit of 60 conditional requests per hour per installation. Syntropic137 minimizes quota usage through several mechanisms:

• ETag caching: Uses If-None-Match headers for conditional requests. 304 Not Modified responses still count against the limit but return no data.
• Selective polling: Only repositories with active triggers are polled. Repos without triggers consume zero API calls.
• Adaptive intervals: In Safety Net mode (webhooks healthy), polling drops to every 5 minutes, roughly 12 requests per hour per repo.
• X-Poll-Interval: The poller respects GitHub's recommended minimum interval from the X-Poll-Interval response header.

Quota estimates

Configuration

All polling settings use the SYN_POLLING_ environment variable prefix:

Disabling Polling

If you have reliable webhook delivery and want zero Events API quota usage:

SYN_POLLING_DISABLED=true

This is recommended for production deployments with a stable public webhook URL or Cloudflare Tunnel. The webhook endpoint continues to work normally regardless of this setting.