telegram-signal-parser-to-webhook

KO | EN

gitlite — search

#hacktoberfest #typescript #llm #android #machine-learning #deep-learning #linux #docker #nodejs #macos #java #kubernetes #vue #security

telegram-signal-parser-to-webhook

(★ 16)

A Regex-based parser that "reads" trade signals from Telegram groups and converts them into structured JSON for automated execution.

telegram-signal-parser-to-webhook Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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

```text
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

```text
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:

```json
{
  "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:

```json
{
  "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

```bash
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:

```bash
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)

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

Input format:

```text
<source>|<message>
```

Example:

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

### 2) Replay dead-letter queue

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

### 3) Telegram listener (Telethon)

```bash
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:

```bash
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](https://github.com/leionion)

## Disclaimer

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

telegram-signal-parser-to-webhook

telegram-signal-parser-to-webhook Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

telegram-signal-parser-to-webhook

telegram-signal-parser-to-webhook Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README