{"id":24685198,"url":"https://github.com/codeasashu/hookrelay","last_synced_at":"2025-07-29T01:36:12.137Z","repository":{"id":272359596,"uuid":"916328247","full_name":"codeasashu/HookRelay","owner":"codeasashu","description":"A webhook notification delivery service","archived":false,"fork":false,"pushed_at":"2025-05-30T13:32:20.000Z","size":244,"stargazers_count":0,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-06T02:42:09.251Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codeasashu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-01-13T22:09:31.000Z","updated_at":"2025-05-30T06:59:22.000Z","dependencies_parsed_at":"2025-03-21T20:42:53.619Z","dependency_job_id":"d4a97f9e-c2c3-4ee7-8712-633376ad4d79","html_url":"https://github.com/codeasashu/HookRelay","commit_stats":null,"previous_names":["codeasashu/hookrelay"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/codeasashu/HookRelay","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeasashu%2FHookRelay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeasashu%2FHookRelay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeasashu%2FHookRelay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeasashu%2FHookRelay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codeasashu","download_url":"https://codeload.github.com/codeasashu/HookRelay/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeasashu%2FHookRelay/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267616731,"owners_count":24116162,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-28T02:00:09.689Z","response_time":68,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2025-01-26T15:18:16.765Z","updated_at":"2025-07-29T01:36:12.113Z","avatar_url":"https://github.com/codeasashu.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HookRelay\n\nHookRelay is an open-source, highly available webhook notification service designed for low-latency and high scalability. It provides seamless integration for producers and consumers, enabling efficient event-driven communication with support for rate limiting, retries, and endpoint failure notifications.\n\n## Features\n\n1. **Fanout**: Allows clients to subscribe to specific event types and receive notifications via webhooks. A client can configure multiple receivers for greater flexibility.\n2. **Webhook Gateway**: Consumes events from multiple sources, including REST APIs, AWS SNS, and WebSockets.\n3. **Rate Limiting**: Throttles event delivery to endpoints at a configurable rate per endpoint.\n4. **Retry Mechanism**: Supports constant time and exponential backoff with jitter. Includes batch retry functionality for failed endpoints.\n5. **Dashboard**: Provides an intuitive interface to manage endpoints, subscriptions, events, and sources. Allows debugging, retrying events, and configuring settings.\n6. **Endpoint Failure Notifications**: Notifies users via email or Slack when endpoints consecutively fail to process events, automatically disabling them to prevent further issues.\n\n## Core Concepts\n\n### Endpoint\n\nAn endpoint is a valid HTTP URL capable of receiving webhook events. Each endpoint can be configured with:\n\n- **Timeout**: Maximum duration to wait for a response.\n- **Rate Limit**: Ensures compatibility with consumer capacity.\n- **Authentication**: Adds an extra layer of security.\n- **Owner ID**: Groups endpoints for fanning out events.\n\n### Sources\n\nSources define how events are ingested into HookRelay. Supported sources include:\n\n- **REST API**: Directly send events to the service.\n- **AWS SNS**: Listen to AWS SNS topics for event ingestion.\n- **WebSockets**: Real-time event streaming.\n\n### Subscription\n\nA subscription maps an endpoint to one or more event types. Subscriptions are created by admins and allow targeted event delivery.\n\n### Event\n\nAn event is a message sent to HookRelay in the following format:\n\n```json\n{\n  \"payload\": {...},\n  \"owner_id\": \"{string}\",\n  \"event_type\": \"{string}\"\n}\n```\n\nBased on the `event_type`, HookRelay delivers the event to all matching subscriptions. The `owner_id` ensures targeted delivery to related endpoints.\n\n## Architecture Overview\n\nThe architecture of HookRelay consists of the following key components:\n\n- **Event Sources**: REST API, AWS SNS, WebSockets.\n- **Event Dispatcher**: Handles fanout logic, matching events to subscriptions.\n- **Rate Limiter**: Implements per-endpoint rate limiting using Redis.\n- **Retry Queue**: Processes failed events with retry algorithms using Kafka or NATS.\n- **Database**: PostgreSQL for storing metadata, Redis for caching.\n- **Notification System**: Integrates with email and Slack for alerts.\n- **Dashboard**: Admin interface for monitoring and configuration.\n\n## Getting Started\n\n### Prerequisites\n\n- Go 1.20+\n- Docker\n- PostgreSQL\n- Redis\n- Kafka or NATS (optional for pub/sub)\n\n### Installation\n\n1. Clone the repository:\n\n   ```bash\n   git clone https://github.com/codeasashu/hookrelay.git\n   cd hookrelay\n   ```\n\n2. Build and run the application:\n\n   ```bash\n   make build\n   make run\n   ```\n\n3. Deploy to Kubernetes:\n   ```bash\n   kubectl apply -f k8s/\n   ```\n\n### Configuration\n\nUpdate the `config.yaml` file to match your environment. Example configuration:\n\n```yaml\nserver:\n  port: 8080\n\nrateLimiter:\n  redis:\n    address: localhost:6379\n\nretryQueue:\n  kafka:\n    brokers: [\"localhost:9092\"]\n```\n\n### Migrations\n\nMigrations are created using [golang-migrate](https://github.com/golang-migrate/migrate) tool. Running command such as:\n\n```sh\nbrew install golang-migrate\n\n# Create a migration for postgresql\nmigrate create -ext sql -dir migrations/postgres -seq create_subscriptions\n\n# Create a migration for mysql\nmigrate create -ext sql -dir migrations/mysql -seq create_subscriptions\n\n# Apply all migration (for postgresql)\nexport POSTGRESQL_URL='postgres://admin:admin@localhost:5432/hookrelay?sslmode=disable'\nmigrate -database ${POSTGRESQL_URL} -path migrations/postgres up\n\n# Apply all migration (for mysql)\nexport MYSQL_URL='mysql://admin:admin@tcp(localhost:3306)/hookrelay?x-tls-insecure-skip-verify=false'\nmigrate -database ${MYSQL_URL} -path migrations/mysql up\n```\n\nwill create migrations\n\n## Contributing\n\nContributions are welcome! Please read the [CONTRIBUTING.md](CONTRIBUTING.md) file for guidelines.\n\n## License\n\nHookRelay is licensed under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeasashu%2Fhookrelay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodeasashu%2Fhookrelay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeasashu%2Fhookrelay/lists"}