Sky Notify

Sky Notify is a focused notification-delivery service for the SKYCOIN4444 engineering ecosystem. It provides durable submission, idempotency, retry/dead-letter state, operational endpoints, and explicit provider delivery results without claiming delivery before the configured provider actually succeeds.

What is implemented

• FastAPI HTTP API on Python 3.12
• SQLite-backed durable notification records
• idempotent submissions keyed by caller-provided idempotency keys
• pending, sending, delivered, and dead_letter lifecycle states
• bounded retry budgets with exponential delay
• log adapter for deterministic local/CI verification
• HTTPS webhook adapter with an explicit hostname allowlist
• redirect refusal for webhook calls
• optional constant-time bearer-token protection
• 64 KiB bounded JSON payloads
• /healthz, /readyz, and /metrics
• non-root container packaging and persistent /app/data state
• compile, Ruff, pytest, pip-audit, Docker-build, and non-root CI gates

Run locally

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
uvicorn src.main:app --host 127.0.0.1 --port 8000

To allow webhook delivery, configure exact destination hostnames:

export NOTIFY_WEBHOOK_HOSTS="hooks.example.com,events.example.net"

Optionally protect mutation/read endpoints:

export NOTIFY_API_TOKEN="replace-with-a-secret-at-least-16-characters"

Example submission

curl -X POST http://127.0.0.1:8000/api/v1/notifications \
-H 'Content-Type: application/json' \
-d '{"channel":"log","destination":"stdout","payload":{"event":"build.complete"},"idempotencyKey":"build-123","maxAttempts":3}'
curl -X POST http://127.0.0.1:8000/internal/run-once

Deployment boundary

This release is a single-node durable notification router. It does not claim distributed queue semantics, exactly-once external delivery, multi-region failover, email/SMS/push provider integrations, tenant isolation, or external compliance certification. Webhook recipients must be explicitly allowlisted. Production operators remain responsible for TLS termination, network policy, secret management, database backup, monitoring, and provider credentials.

Repository role

Sky Notify is product #10 in the standalone-product master plan. It remains independently buildable while exposing a clean notification boundary that can later be integrated into the unified SKYCOIN4444 platform.