Problem

No way to automatically index shards when new versions are published to GitHub.

Current State

Manual intervention required for every shard update.

Requirements

• Create POST /api/webhooks/github endpoint
• Verify webhook signature using secret (HMAC SHA256)
• Parse release/tag push events from GitHub
• Enqueue IndexShardWorker for new versions
• Add webhook secret to Kubernetes secrets
• Handle webhook retries and idempotency
• Log webhook events for debugging

Implementation Details

Endpoint Location

Create apps/crystalshards/src/actions/api/webhooks/github.cr

GitHub Events to Handle

• release.published - New release created
• push (tags only) - New tag pushed (e.g., v1.2.3)

Signature Verification

# Verify X-Hub-Signature-256 header
expected = "sha256=" + OpenSSL::HMAC.hexdigest(:sha256, webhook_secret, request.body)
raise "Invalid signature" unless Crypto.fixed_time_compare(expected, signature_header)

Worker Enqueue Logic

if event == "release" && action == "published"
  # Extract shard name from repo (e.g., "owner/repo" -> "repo")
  # Extract version from tag_name (e.g., "v1.2.3" -> "1.2.3")
  IndexShardWorker.enqueue(shard_name: shard_name, version: version)
end

Kubernetes Secret

apiVersion: v1
kind: Secret
metadata:
  name: crystalshards-secrets
  namespace: crystalshards
stringData:
  github-webhook-secret: <generate-random-secret>

Idempotency

• Check if shard version already exists in database
• Skip indexing if version already processed
• Return 200 OK regardless to acknowledge webhook

Estimated Effort

2-4 hours

Priority

HIGH - Enables automatic shard indexing

Application

CrystalShards.org

Acceptance Criteria

• POST /api/webhooks/github endpoint created
• Webhook signature verification implemented
• Release events trigger IndexShardWorker
• Tag push events trigger IndexShardWorker
• Webhook secret stored in Kubernetes secret
• Idempotency handled (duplicate events ignored)
• Integration tests cover webhook flow
• Documentation for setting up webhooks on GitHub repos