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 :3000cd dashboard && npm install && npm run dev # dashboard on :3001

---

License

MIT © stellar-notify contributors