Telegram Signal Parser To Webhook

Parse human-written Telegram trading signals into deterministic JSON and route them safely to downstream webhook infrastructure.

What is implemented

This repository now includes a production-style Python implementation with:

• Source-specific regex parser profiles
• Entry parsing for range and market-style signals
• Symbol alias normalization (GOLD -> XAUUSD, etc.)
• Multiline TP extraction (TP1, TP2, TP3, ...)
• Dedupe window to prevent repeated execution from duplicate posts
• Parse-failure routing (log, ignore, dead_letter)
• Dead-letter queue (JSONL) and replay mode
• Optional source-level transforms in normalized payloads
• HMAC SHA-256 signing for webhook delivery
• paper mode and live mode
• Automated test suite with pytest

Project structure

telegram-signal-parser-to-webhook/
├── main.py
├── config.yaml
├── config.example.yaml
├── requirements.txt
├── pyproject.toml
├── signal_parser/
│   ├── __init__.py
│   ├── config.py
│   ├── dead_letter.py
│   ├── dedupe.py
│   ├── models.py
│   ├── parser.py
│   ├── pipeline.py
│   └── webhook.py
└── tests/
    ├── test_parser.py
    └── test_pipeline.py

Architecture

Telegram Message
  -> source profile selection
  -> regex parse + normalization
  -> schema-like normalized signal object
  -> dedupe check
  -> paper mode (no outbound call) OR live webhook POST
  -> dead-letter on parse fail / delivery fail (config dependent)

Signal output shape

Successful parse (signal.parsed) example:

{
  "event": "signal.parsed",
  "parser_profile": "xauusd_swing_v1",
  "source": "vip-gold-room",
  "message_id": "184229",
  "timestamp": "2026-04-14T00:00:00+00:00",
  "raw_message": "BUY GOLD NOW 2162-2164 SL 2156 TP1 2168 TP2 2174",
  "normalized": {
    "action": "buy",
    "symbol": "XAUUSD",
    "entry": {"type": "range", "min": 2162.0, "max": 2164.0},
    "stop_loss": 2156.0,
    "take_profit": [2168.0, 2174.0],
    "source": "vip-gold-room",
    "account": "metals"
  },
  "webhook": {
    "status": "skipped",
    "reason": "paper mode"
  }
}

Parse failure (signal.unmatched) example:

{
  "event": "signal.unmatched",
  "source": "vip-gold-room",
  "message_id": "184230",
  "timestamp": "2026-04-14T00:00:01+00:00",
  "parser_profile": "",
  "reason": "xauusd_swing_v1: missing stop loss token",
  "raw_message": "BUY GOLD NOW 2162-2164 TP1 2168 TP2 2174"
}

Installation

git clone https://github.com/leionion/telegram-signal-parser-to-webhook.git
cd telegram-signal-parser-to-webhook
python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt

Configuration

Use config.example.yaml as the base template:

cp config.example.yaml config.yaml

Main sections:

• telegram: API credentials, session path, and source list
• parsers: source-bound parser profiles with regex rules
• webhook: endpoint URL, secret, timeout, retry count
• routing: parse-fail behavior, dedupe window, runtime mode, dead-letter path

Run modes

1) Local stdin demo (fastest validation path)

python main.py --config config.yaml --stdin

Input format:

<source>|<message>

Example:

vip-gold-room|BUY GOLD NOW 2162-2164 SL 2156 TP1 2168 TP2 2174

2) Replay dead-letter queue

python main.py --config config.yaml --replay-file ./data/dead_letter.jsonl

3) Telegram listener (Telethon)

python main.py --config config.yaml --telegram

Webhook security

Outbound requests include:

• X-Signal-Timestamp
• X-Signal-Signature (HMAC SHA-256 over timestamp.payload)

This allows downstream services to verify authenticity and freshness.

Testing

Run tests:

pytest

Current tests cover:

• successful parse and alias normalization
• parse failure reason reporting
• dedupe behavior
• dead-letter file creation
• deterministic HMAC signature generation

Current implementation status

This repository now targets the advanced implementation scope. The previously described "initial version" is superseded.

Implemented from the prior roadmap:

• Dedupe windows
• Better multiline TP extraction
• Dead-letter queue + replay
• Source-specific transforms
• HMAC signing for webhook payloads

Not yet implemented:

• Confidence scoring layer
• Multi-webhook fanout by asset class
• Web dashboard for parser profile testing

Contact

• GitHub: @leionion

Disclaimer

This software is infrastructure tooling, not financial advice. Always validate parser behavior in paper mode before any live trading workflow.