README.md

Unthread Webhook Server 🎫⚡

A production-ready Node.js webhook server for Unthread.io integration. Built with TypeScript, Express.js, and Redis for reliable webhook event processing with HMAC signature verification and intelligent platform detection.

🤗 Special Thanks

🤝 Partner Organizations

These outstanding organizations partner with us to support our open-source work:

💎 Platinum Sponsor
Unthread Streamlined support ticketing for modern teams.

💸 Sponsored Ads

Open source development is resource-intensive. These sponsored ads help keep Log Engine free and actively maintained while connecting you with tools and services that support open-source development.

🚀 Quick Start

Requirements: Node.js 20+, Redis, Yarn

# 1. Install dependencies
yarn install

# 2. Configure environment
cp .env.example .env
# Edit .env with your Unthread webhook secret

# 3. Start Redis (choose one)
redis-server                          # Local installation
brew services start redis             # macOS
sudo systemctl start redis-server     # Linux
docker run -d -p 6379:6379 redis:alpine  # Docker

# 4. Run the server
yarn dev        # Development with auto-reload
yarn start      # Production mode

Server runs on http://localhost:3000 with endpoints:

• GET /health - Health check
• POST /unthread-webhook - Webhook endpoint

🐳 Docker Setup

# Copy Docker template
cp .env.docker.example .env.docker
# Edit .env.docker with your secrets

# Start Redis for Docker
docker run -d --name docker-redis -p 6379:6379 redis:7-alpine

# Run with Docker (using cloud builder)
docker run --name docker-unthread-webhook-server --env-file .env.docker -p 3000:3000 --rm wgtechlabs/unthread-webhook-server:latest

Environment Files:

• .env - Local development (Node.js directly)
• .env.docker - Docker testing (redis://host.docker.internal:6379)
• .env.example + .env.docker.example - Safe templates (committed to git)

⚙️ Configuration

Environment Variables

Create a .env file from the example:

cp .env.example .env

Required variables:

Variable	Description	Default	Required
UNTHREAD_WEBHOOK_SECRET	Your Unthread.io signing secret	-	✅
NODE_ENV	Environment mode	development	❌
PORT	Server port	3000	❌
TARGET_PLATFORM	Platform identifier (e.g., telegram, discord)	telegram	❌
REDIS_URL	Redis connection URL	redis://localhost:6379	❌

Getting Your Unthread Signing Secret

1. Go to Unthread Dashboard
2. Navigate to Webhooks settings
3. Copy your signing secret to UNTHREAD_WEBHOOK_SECRET in .env
4. Set your webhook URL to: https://your-domain.com/unthread-webhook

For local testing, use ngrok: ngrok http 3000

🔧 How It Works

1. Webhook Reception: Receives POST requests from Unthread.io at /unthread-webhook
2. Security: Validates HMAC-SHA256 signatures using your webhook secret
3. Deduplication: Prevents duplicate event processing with Redis TTL cache
4. Platform Detection: Identifies if events come from dashboard or target platform
5. Queue Publishing: Sends processed events to Redis unthread-events queue

📊 Event Processing

Supported Events

• url_verification - Automatic URL verification
• conversation_created - New conversations
• conversation_updated - Status changes
• conversation_deleted - Conversation removal
• message_created - New messages

Redis Queue Format

Events are queued with this structure:

{
  "platform": "unthread",
  "targetPlatform": "telegram",
  "type": "message_created", 
  "sourcePlatform": "dashboard",
  "data": {
    "eventId": "evt_123456789",
    "conversationId": "conv_abc123",
    "content": "Hello from support!",
    "eventTimestamp": 1733097600000
  },
  "timestamp": 1733097600000
}

💻 Development

Build Commands

yarn clean      # Clean previous builds
yarn build      # Build for production
yarn type-check # TypeScript type checking only
yarn dev        # Development with hot-reload
yarn start      # Run production build

Project Structure

src/
├── app.ts              # Main application entry
├── config/             # Configuration files
├── controllers/        # Request handlers
├── middleware/         # Auth & validation
├── services/           # Business logic
├── types/              # TypeScript types
└── utils/              # Helper functions

🔍 Monitoring

Health Check

curl http://localhost:3000/health

Healthy Response:

{
  "status": "OK",
  "redis": "connected",
  "timestamp": "2025-06-21T12:00:00.000Z"
}

Error Response:

{
  "status": "ERROR", 
  "redis": "disconnected",
  "timestamp": "2025-06-21T12:00:00.000Z"
}

Troubleshooting

Redis Connection Issues:

• Verify Redis is running: redis-cli ping
• Check REDIS_URL in your .env file
• Review server logs for connection errors

Platform Detection Issues:

• Check logs for detection summary details
• Verify event structure matches Unthread format
• Events may be classified as "unknown" for edge cases

🎯 Contributing

Contributions are welcome, create a pull request to this repo and I will review your code. Please consider to submit your pull request to the dev branch. Thank you!

When contributing, please ensure your code follows the existing TypeScript patterns and includes appropriate error handling.

🙏 Sponsor

Like this project? Leave a star! ⭐⭐⭐⭐⭐

There are several ways you can support this project:

• Become a sponsor and get some perks! 💖
• Buy me a coffee if you just love what I do! ☕

⭐ GitHub Star Nomination

Found this project helpful? Consider nominating me (@warengonzaga) for the GitHub Star program! This recognition supports ongoing development of this project and my other open-source projects. GitHub Stars are recognized for their significant contributions to the developer community - your nomination makes a difference and encourages continued innovation!

📃 License

Licensed under GNU General Public License v3.0 - ensuring modifications remain open source.

📝 Author

This project is created by Waren Gonzaga under WG Technology Labs, with the help of awesome contributors.

---

💻 Made with ❤️ by Waren Gonzaga under WG Technology Labs