stellar-notify 🔔

Open-source webhook & notification engine for Stellar blockchain events.

---

The problem

Horizon is being deprecated. Allium and Alchemy fill the indexing gap — but they are paid, centralised services. There is no open-source, self-hostable tool that lets a developer say:

"Send me a webhook when wallet X receives a payment, or when contract Y emits event Z."

Ethereum has The Graph, Alchemy Notify, and dozens of open-source alternatives. Stellar has nothing community-owned. Until now.

---

Features

Feature	Status
Stream Horizon payments per account	✅
Stream account activity (all tx)	✅
Stream all network transactions	✅
Poll Soroban contract events (RPC)	✅
Webhook delivery with HMAC-SHA256	✅
Email notifications (SMTP)	✅
Telegram bot notifications	✅
Exponential back-off retries	✅
Cursor persistence (resume on restart)	✅
REST API with API-key auth	✅
Next.js dashboard	✅
Docker + docker-compose	✅
One-click Railway deploy	🔜
Discord / Slack channels	🔜
PostgreSQL support	🔜

---

Quick start

Option 1 — Docker (recommended)

git clone https://github.com/stellar-notify/stellar-notify.git
cd stellar-notify
cp .env.example .env   # edit values
docker-compose up -d

The engine runs on http://localhost:3000 and the dashboard on http://localhost:3001.

Option 2 — Local Node.js

# Prerequisites: Node.js >= 18
npm install
cp .env.example .env   # edit values
npm run migrate        # initialise SQLite
npm start

---

Configuration

Copy .env.example to .env and fill in the values. Key variables:

Variable	Description	Default
STELLAR_NETWORK	testnet or mainnet	testnet
HORIZON_URL	Custom Horizon endpoint	network default
SOROBAN_RPC_URL	Soroban RPC endpoint	network default
ADMIN_PASSWORD	Password to issue API keys	changeme
DB_PATH	SQLite file path	./data/stellar-notify.db
SMTP_*	Email configuration	—
TELEGRAM_BOT_TOKEN	Telegram bot token	—

---

API

Issue an API key

curl -X POST http://localhost:3000/api/auth/keys \
  -H "Content-Type: application/json" \
  -d '{"admin_password":"changeme","label":"my-app"}'
# Returns: { "key": "snk_…" }  — store this, shown only once

Create a subscription

curl -X POST http://localhost:3000/api/subscriptions \
  -H "Authorization: Bearer snk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "payment",
    "label": "My wallet",
    "filter": {
      "account": "GABC…XYZ",
      "asset_code": "USDC",
      "min_amount": "10"
    },
    "channel": "webhook",
    "channel_config": {
      "url": "https://your-app.com/hooks/stellar",
      "secret": "optional-signing-secret"
    }
  }'

Subscription types

Type	Filter fields
payment	account, asset_code, min_amount
account_activity	account (required)
transaction	account (optional)
contract_event	contract_id, topics, poll_interval_ms

Notification channels

Channel	Config fields
webhook	url, secret (HMAC-SHA256 optional)
email	to, subject_prefix
telegram	chat_id

Webhook payload example

{
  "event_type": "payment",
  "id": "…",
  "from": "GABC…",
  "to": "GXYZ…",
  "amount": "100.0000000",
  "asset_code": "USDC",
  "asset_issuer": "GA5ZS…",
  "transaction_hash": "abc123…",
  "created_at": "2025-01-01T00:00:00Z"
}

Requests include X-StellarNotify-Signature: sha256=<hmac> when a secret is configured.

---

Dashboard

Open http://localhost:3001. Enter your API key (issued above) to access:

• Create / pause / delete subscriptions
• Filter by event type and channel
• View delivery log with retry on failure
• Live stats (active subs, delivered, pending, failed)

---

Architecture

┌─────────────────────────────────────────────────────┐
│                   stellar-notify                     │
│                                                      │
│  ┌───────────┐    ┌──────────────┐   ┌──────────┐  │
│  │  Horizon  │───▶│ StreamManager│──▶│ Delivery │  │
│  │   SSE     │    │  (per-sub)   │   │ Service  │  │
│  └───────────┘    └──────────────┘   └────┬─────┘  │
│  ┌───────────┐                            │        │
│  │ Soroban   │───▶  polling loop     ┌────▼──────┐ │
│  │   RPC     │                       │  SQLite   │ │
│  └───────────┘                       └────┬──────┘ │
│                                           │        │
│  ┌─────────────────────────────┐    ┌─────▼──────┐ │
│  │        REST API             │    │ Channels:  │ │
│  │  /subscriptions             │    │ webhook    │ │
│  │  /deliveries                │    │ email      │ │
│  │  /auth/keys                 │    │ telegram   │ │
│  └─────────────────────────────┘    └────────────┘ │
└─────────────────────────────────────────────────────┘
         ▲
   Next.js Dashboard  (port 3001)

---

Contributing

PRs are welcome! See CONTRIBUTING.md for guidelines.

npm install
cp .env.example .env
npm start   # engine on :3000
cd dashboard && npm install && npm run dev   # dashboard on :3001

---

License

MIT © stellar-notify contributors