{"id":43514858,"url":"https://github.com/shanth1/webhook-dispatcher","last_synced_at":"2026-02-03T13:39:11.328Z","repository":{"id":320624300,"uuid":"1082053127","full_name":"shanth1/webhook-dispatcher","owner":"shanth1","description":"A flexible notification manager. Aggregates webhooks from different services, verifies signatures, formats messages using Go templates, and sends them to the right recipients","archived":false,"fork":false,"pushed_at":"2025-11-26T08:06:43.000Z","size":131,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-29T07:56:44.939Z","etag":null,"topics":["dispatcher","github-webhooks","go","golang","kanboard","notifications","smtp","telegram-bot","webhook"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shanth1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-23T17:01:33.000Z","updated_at":"2025-11-26T08:10:40.000Z","dependencies_parsed_at":"2025-10-28T12:20:17.970Z","dependency_job_id":"c5e493d8-b53b-4d9c-bc9e-6deb67df0ee2","html_url":"https://github.com/shanth1/webhook-dispatcher","commit_stats":null,"previous_names":["shanth1/telegram-webhook","shanth1/github-webhook-dispatcher","shanth1/webhook-dispatcher"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/shanth1/webhook-dispatcher","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shanth1%2Fwebhook-dispatcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shanth1%2Fwebhook-dispatcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shanth1%2Fwebhook-dispatcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shanth1%2Fwebhook-dispatcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shanth1","download_url":"https://codeload.github.com/shanth1/webhook-dispatcher/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shanth1%2Fwebhook-dispatcher/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29046672,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-03T10:09:22.136Z","status":"ssl_error","status_checked_at":"2026-02-03T10:09:16.814Z","response_time":96,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dispatcher","github-webhooks","go","golang","kanboard","notifications","smtp","telegram-bot","webhook"],"created_at":"2026-02-03T13:39:10.562Z","updated_at":"2026-02-03T13:39:11.311Z","avatar_url":"https://github.com/shanth1.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HookRelay (Webhook Dispatcher)\n\n[Russian Version](README.ru.md)\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/shanth1/hookrelay)](https://goreportcard.com/report/github.com/shanth1/hookrelay)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA flexible Go-based service to receive webhooks from multiple sources like GitHub, Kanboard, and custom applications, and dispatch them as formatted notifications to various channels like Telegram and Email.\n\n## Overview\n\n`hookrelay` is a lightweight, configurable server that acts as a bridge between your services and your notification channels. It listens for webhook events, verifies their authenticity, formats them into human-readable messages using Go templates, and broadcasts them to a pre-configured list of recipients.\n\n## Features\n\n- **Multi-Source Webhook Handling**: Natively supports webhooks from **GitHub**, **Kanboard**, and **Custom** sources.\n- **Secure Verification**:\n  - **GitHub**: HMAC signature (`X-Hub-Signature-256`).\n  - **Kanboard**: URL query token.\n  - **Custom**: Authentication header token (`X-Auth-Token`).\n- **Multi-Channel Notifications**: Support for **Telegram** and **Email (SMTP)** via the `notifiers` configuration.\n- **Message Templating**: Uses embedded Go `html/template` files to format notifications.\n  - Supports custom fallback for unknown events.\n  - Specific templates for complex events (e.g., GitHub Push, Kanboard Task Create).\n- **Service Discovery \u0026 Health**: Exposes endpoints for health checks and configuration discovery.\n- **Graceful Shutdown**: Handles `SIGINT`/`SIGTERM` for clean shutdown.\n- **YAML Configuration**: Single file configuration for endpoints, credentials, and routing.\n\n## Prerequisites\n\n- [Go](https://golang.org/dl/) (version 1.23 or higher)\n- [Make](https://www.gnu.org/software/make/) (optional, for build commands)\n\n## Getting Started\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/shanth1/hookrelay.git\ncd hookrelay\n```\n\n### 2. Create Configuration\n\nCopy the example configuration to create your local config:\n\n```bash\nmake configs\n# Creates config/local.yaml and config/production.yaml\n```\n\n### 3. Build\n\n```bash\nmake build\n# Binary will be created at ./build/hookrelay\n```\n\n## Configuration\n\nThe application is configured using a YAML file.\n\n**Example `config/production.yaml`:**\n\n```yaml\n# Address to listen on\naddr: ':8080'\nenv: 'production'\n\n# If true, events without a specific template file will be ignored\n# instead of using the default template.\ndisable_unknown_templates: false\n\nlogger:\n  level: 'info'\n  app: 'hookrelay'\n  service: 'webhook-service'\n\n# 1. Define incoming Webhooks (Sources)\nwebhooks:\n  - name: 'github-main'\n    path: '/webhook/github'\n    type: 'github'\n    secret: 'YOUR_GITHUB_WEBHOOK_SECRET'\n    recipients:\n      - 'Dev Team (Telegram)'\n      - 'Tech Lead (Email)'\n\n  - name: 'kanboard-tasks'\n    path: '/webhook/kanboard'\n    type: 'kanboard'\n    secret: 'YOUR_KANBOARD_TOKEN'\n    base_url: 'https://kanboard.your-domain.com' # Required for generating links\n    recipients:\n      - 'Dev Team (Telegram)'\n\n  - name: 'monitoring'\n    path: '/webhook/custom'\n    type: 'custom'\n    secret: 'YOUR_CUSTOM_AUTH_TOKEN'\n    recipients:\n      - 'Dev Team (Telegram)'\n\n# 2. Define Notifiers (Channels)\nnotifiers:\n  - name: 'telegram-bot'\n    type: 'telegram'\n    settings:\n      token: '123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11'\n\n  - name: 'smtp-server'\n    type: 'email'\n    settings:\n      host: 'smtp.gmail.com'\n      port: 587\n      username: 'notifier@example.com'\n      password: 'app-specific-password'\n      from: 'HookRelay \u003cnotifier@example.com\u003e'\n\n# 3. Define Recipients (Routing)\nrecipients:\n  - name: 'Dev Team (Telegram)'\n    notifier: 'telegram-bot' # Must match a notifier name above\n    target: '-100123456789' # Telegram Chat ID\n\n  - name: 'Tech Lead (Email)'\n    notifier: 'smtp-server'\n    target: 'lead@example.com' # Email Address\n```\n\n## API Endpoints\n\nThe server exposes the following endpoints:\n\n- `POST /webhook/{path}`: Endpoints defined in your config for receiving events.\n- `GET /health`: Health check (returns `200 OK`).\n- `GET /webhooks`: Returns a list of supported webhook types.\n- `GET /notifiers`: Returns a list of supported notifier types.\n\n## Running the Application\n\n**Using Make (Development):**\n\n```bash\nmake run\n```\n\n**Using Binary (Production):**\n\n```bash\n./build/hookrelay --config config/production.yaml\n```\n\n## Setting up Sources\n\n### GitHub\n\n1. Go to Repo Settings -\u003e Webhooks.\n2. Payload URL: `http://your-server/webhook/github`.\n3. Content type: `application/json` or `application/x-www-form-urlencoded`.\n4. Secret: Must match the `secret` in `webhooks` config.\n\n### Kanboard\n\n1. Go to Project Settings -\u003e Webhooks.\n2. Webhook URL: `http://your-server/webhook/kanboard?token=YOUR_KANBOARD_TOKEN`.\n3. Note: The token in the URL must match the `secret` in the config.\n\n### Custom\n\n1. Send `POST` to `http://your-server/webhook/custom`.\n2. Header `X-Auth-Token`: Must match `secret` in config.\n3. Body: Plain text or JSON.\n\n## Testing\n\nUse the provided `webhook.sh` script to simulate events:\n\n```bash\n# GitHub Push Event\n./webhook.sh github push\n\n# Kanboard Task Creation\n./webhook.sh kanboard task.create\n\n# Custom Message\n./webhook.sh custom \"Production server is unreachable!\"\n```\n\nRun unit tests:\n\n```bash\nmake test\n```\n\n## Project Structure\n\n```\n.\n├── cmd/                # Entry point\n├── config/             # Configuration files and structs\n├── internal/\n│   ├── adapters/       # Inbound (GitHub/Kanboard) \u0026 Outbound (TG/Email) logic\n│   ├── app/            # App lifecycle and initialization\n│   ├── core/           # Domain models and interfaces (ports)\n│   ├── service/        # Business logic (Routing)\n│   └── transport/      # HTTP server and middleware\n└── templates/          # Embedded template files\n```\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshanth1%2Fwebhook-dispatcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshanth1%2Fwebhook-dispatcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshanth1%2Fwebhook-dispatcher/lists"}