hook-relay

Overview

hook-relay receives webhooks at a server that acts as a single endpoint, and broadcasts these to clients connected via WebSocket. Clients forward the requests to another endpoint (e.g., a development server).

Use case

$3

When developing Slack Apps, you can only configure a single endpoint URL. This creates inefficiency when multiple developers need to work simultaneously, as each developer would traditionally need their own Slack App and a proxy solution like ngrok to route requests to their local environment.

With hook-relay, you can maintain just one Slack App and endpoint while allowing multiple developers to connect to it. Each developer can filter for only the events they need, making the development process more efficient and collaborative.

$3

When developing OAuth integrations, you need to receive callbacks on your local development server. Unlike webhooks, it's not always clear which client should receive the callback based on its content.

hook-relay solves this by allowing you to register one-shot callback receivers. This works well for development as long as multiple developers don't need callbacks at exactly the same time.

Usage

``
$ hook-relay-server --help
Usage: hook-relay-server [options]

Options:
-V, --version output the version number
--port Port to listen on (default: 3000, env: PORT)
--challenge-passphrase Passphrase for challenge response (env: CHALLENGE_PASSPHRASE)
--log-level Log level (default: "info", env: LOG_LEVEL)
-h, --help display help for command
`

`
$ hook-relay-client --help
Usage: hook-relay-client [options]

Options:
-V, --version output the version number
--server-endpoint Server endpoint URL
--forward-endpoint Forward endpoint URL
--path Path to use
--log-level Log level (default: "info")
--filter-body-regex Filter body regex
--reconnect-interval-ms Reconnect interval in milliseconds (default: "1000")
--port Port to listen on (default: 3001, env: PORT)
--challenge-passphrase Passphrase for challenge response (env: CHALLENGE_PASSPHRASE)
-h, --help display help for command
`

`


Register a oneshot callback


$ client_id=$(curl -SsfL localhost:3001 | jq -r .clientId) # get client id by HTTP
$ curl -H 'content-type: application/json' \
-XPOST http://localhost:3000/callback/oneshot/register \
-d "{\"path\":\"/auth/redirect\",\"clientId\":\"$client_id\"}"
{"callbackUrl":"http://localhost:3000/callback/oneshot/auth/redirect"}
`

Security Considerations

$3

For production environments, it is strongly recommended to use HTTPS/WSS for all communications:

- Server: Deploy behind a reverse proxy (nginx, Caddy, etc.) with SSL/TLS termination
- Client: Connect using wss:// protocol instead of ws://

Example with HTTPS/WSS:
`bash


Server (behind HTTPS reverse proxy)

hook-relay-server --port 3000 --challenge-passphrase $SECRET_PASSPHRASE

Client (connecting via WSS)

hook-relay-client --server-endpoint wss://your-domain.com --forward-endpoint http://localhost:9000 --challenge-passphrase $SECRET_PASSPHRASE
``

$3

- Always use a strong, randomly generated challenge passphrase
- Limit access to the server using firewall rules or network policies
- Consider implementing rate limiting for production use
- Monitor logs for suspicious activity

License

MIT