HookRelay 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.
- Fanout: Allows clients to subscribe to specific event types and receive notifications via webhooks. A client can configure multiple receivers for greater flexibility.
- Webhook Gateway: Consumes events from multiple sources, including REST APIs, AWS SNS, and WebSockets.
- Rate Limiting: Throttles event delivery to endpoints at a configurable rate per endpoint.
- Retry Mechanism: Supports constant time and exponential backoff with jitter. Includes batch retry functionality for failed endpoints.
- Dashboard: Provides an intuitive interface to manage endpoints, subscriptions, events, and sources. Allows debugging, retrying events, and configuring settings.
- Endpoint Failure Notifications: Notifies users via email or Slack when endpoints consecutively fail to process events, automatically disabling them to prevent further issues.
An endpoint is a valid HTTP URL capable of receiving webhook events. Each endpoint can be configured with:
- Timeout: Maximum duration to wait for a response.
- Rate Limit: Ensures compatibility with consumer capacity.
- Authentication: Adds an extra layer of security.
- Owner ID: Groups endpoints for fanning out events.
Sources define how events are ingested into HookRelay. Supported sources include:
- REST API: Directly send events to the service.
- AWS SNS: Listen to AWS SNS topics for event ingestion.
- WebSockets: Real-time event streaming.
A subscription maps an endpoint to one or more event types. Subscriptions are created by admins and allow targeted event delivery.
An event is a message sent to HookRelay in the following format:
{
"payload": {...},
"owner_id": "{string}",
"event_type": "{string}"
}Based on the event_type, HookRelay delivers the event to all matching subscriptions. The owner_id ensures targeted delivery to related endpoints.
The architecture of HookRelay consists of the following key components:
- Event Sources: REST API, AWS SNS, WebSockets.
- Event Dispatcher: Handles fanout logic, matching events to subscriptions.
- Rate Limiter: Implements per-endpoint rate limiting using Redis.
- Retry Queue: Processes failed events with retry algorithms using Kafka or NATS.
- Database: PostgreSQL for storing metadata, Redis for caching.
- Notification System: Integrates with email and Slack for alerts.
- Dashboard: Admin interface for monitoring and configuration.
- Go 1.20+
- Docker
- PostgreSQL
- Redis
- Kafka or NATS (optional for pub/sub)
-
Clone the repository:
git clone https://github.com/codeasashu/hookrelay.git cd hookrelay -
Build and run the application:
make build make run
-
Deploy to Kubernetes:
kubectl apply -f k8s/
Update the config.yaml file to match your environment. Example configuration:
server:
port: 8080
rateLimiter:
redis:
address: localhost:6379
retryQueue:
kafka:
brokers: ["localhost:9092"]Migrations are created using golang-migrate tool. Running command such as:
brew install golang-migrate
# Create a migration for postgresql
migrate create -ext sql -dir migrations/postgres -seq create_subscriptions
# Create a migration for mysql
migrate create -ext sql -dir migrations/mysql -seq create_subscriptions
# Apply all migration (for postgresql)
export POSTGRESQL_URL='postgres://admin:admin@localhost:5432/hookrelay?sslmode=disable'
migrate -database ${POSTGRESQL_URL} -path migrations/postgres up
# Apply all migration (for mysql)
export MYSQL_URL='mysql://admin:admin@tcp(localhost:3306)/hookrelay?x-tls-insecure-skip-verify=false'
migrate -database ${MYSQL_URL} -path migrations/mysql upwill create migrations
Contributions are welcome! Please read the CONTRIBUTING.md file for guidelines.
HookRelay is licensed under the MIT License.