GitHub - webhookx-io/webhookx: The Next-Generation Webhooks Gateway. (original) (raw)

WebhookX

release test-workflow lint-workflow codecov Mentioned in Awesome Go

Join Slack Twitter

WebhookX is an open-source webhooks gateway for message receiving, processing, and delivering.

Architecture

webhookx architecture

Posts

Features

Installation

WebhookX binary provides you both Server and CLI command.

macOS

brew tap webhookx-io/webhookx && brew install webhookx

Linux | Windows

Download the binary distribution on releases.

Get started

Tip

This is only for evaluating features and is not suitable for production. For production deployment, please refer documentation.

1. Start WebhookX using Docker Compose

The docker-compose.yml provides a simple all-in-one (standalone) deployment for quick start.

curl -O https://raw.githubusercontent.com/webhookx-io/webhookx/main/docker-compose.yml && docker compose -f docker-compose.yml up

Once it's running, you will see HTTP 200 response

curl http://localhost:9601

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 Server: WebhookX/0.9.0

{ "version": "0.9.0", "message": "Welcome to WebhookX", "configuration": {} }

2. Setup entities configuration

Let's use a sample declarative configuration webhookx.sample.yml in this quick start.

You may need to install CLI webhookx first, see Installation.

webhookx admin sync webhookx.sample.yml

This command sends the configuration file to WebhookX via Admin API.

Once it is set up, you're ready to send events to WebhookX.

3. Send events to WebhookX

The Ingestion is exposed on port :9600

curl -X POST http://localhost:9600 \
--header 'Content-Type: application/json' \
--data '{
    "event_type": "charge.succeeded",
    "data": {
        "key": "value"
    }
}'

We sent a charge.succeeded event including data to WebhookX, and it will be routed and delivered to endpoints that are defined in the webhookx.sample.ymlfile.

4. Inspect delivery result

Tip

Attempt object represents the delivery result of an event, and contains inspection information.

The Admin is exposed on port :9601

Let's make a request to retrieve the attempt list

curl http://localhost:9601/workspaces/default/attempts

HTTP Response

{ "total": 1, "data": [ { "id": "338lax8Xe774EhimzBukip37Zne", "event_id": "338las8UmbKJZl3aikM44ZWh71P", "endpoint_id": "338lQch7qdBqKvlVxXHcPTjLDTn", "status": "SUCCESSFUL", "attempt_number": 1, "scheduled_at": 1758706646768, "attempted_at": 1758706646819, "trigger_mode": "INITIAL", "exhausted": false, "error_code": null, "request": { "method": "POST", "url": "https://httpbin.org/anything", "headers": null, "body": null }, "response": { "status": 200, "latency": 2402, "headers": null, "body": null }, "created_at": 1758706646769, "updated_at": 1758706649223 } ] }

To inspect the data such as request.headers, request.body, response.headers, and response.body, try

http://localhost:9601/workspaces/default/attempts/338lax8Xe774EhimzBukip37Zne

HTTP Response

{ "id": "338lax8Xe774EhimzBukip37Zne", "event_id": "338las8UmbKJZl3aikM44ZWh71P", "endpoint_id": "338lQch7qdBqKvlVxXHcPTjLDTn", "status": "SUCCESSFUL", "attempt_number": 1, "scheduled_at": 1758706646768, "attempted_at": 1758706646819, "trigger_mode": "INITIAL", "exhausted": false, "error_code": null, "request": { "method": "POST", "url": "https://httpbin.org/anything", "headers": { "Content-Type": "application/json; charset=utf-8", "User-Agent": "WebhookX/0.9.0", "Webhookx-Delivery-Id": "338lax8Xe774EhimzBukip37Zne", "Webhookx-Event-Id": "338las8UmbKJZl3aikM44ZWh71P", "Webhookx-Signature": "v1=37e25342d983c26d783eafe50fe170eaac731383439568e3354315c2e84c5173", "Webhookx-Timestamp": "1758706646", "X-Apikey": "secret" }, "body": "{\n "key": "value"\n }" }, "response": { "status": 200, "latency": 2402, "headers": { "Access-Control-Allow-Credentials": "true", "Access-Control-Allow-Origin": "*", "Content-Length": "778", "Content-Type": "application/json", "Date": "Wed, 24 Sep 2025 09:37:29 GMT", "Server": "gunicorn/19.9.0" }, "body": "{\n "args": {}, \n "data": "{\n \"key\": \"value\"\n }", \n "files": {}, \n "form": {}, \n "headers": {\n "Accept-Encoding": "gzip", \n "Content-Length": "30", \n "Content-Type": "application/json; charset=utf-8", \n "Host": "httpbin.org", \n "User-Agent": "WebhookX/0.9.0", \n "Webhookx-Delivery-Id": "338lax8Xe774EhimzBukip37Zne", \n "Webhookx-Event-Id": "338las8UmbKJZl3aikM44ZWh71P", \n "Webhookx-Signature": "v1=37e25342d983c26d783eafe50fe170eaac731383439568e3354315c2e84c5173", \n "Webhookx-Timestamp": "1758706646", \n "X-Amzn-Trace-Id": "Root=1-68d3bbd7-195b190632c27c547358dbee", \n "X-Apikey": "secret"\n }, \n "json": {\n "key": "value"\n }, \n "method": "POST", \n "origin": "0.0.0.0", \n "url": "https://httpbin.org/anything\"\n}\n" }, "created_at": 1758706646769, "updated_at": 1758706649223 }

To explore all the API, see openapi.webhookx.io.

CLI

Usage:
  webhookx [command]

Available Commands:
  admin       Admin commands
  completion  Generate the autocompletion script for the specified shell
  db          Database commands
  help        Help about any command
  start       Start server
  version     Print the version

Flags:
  -h, --help      help for webhookx
      --verbose   Verbose logging.

Use "webhookx [command] --help" for more information about a command.

Runtime dependencies

Requires the following runtime dependencies to work:

Status and Compatibility

The project is currently under active development, hence breaking changes may be introduced in minor releases.

The public API will strictly follow semantic versioning after v1.0.0.

Contributing

We ❤️ pull requests, and we’re continually working hard to make it as easy as possible for developers to contribute.

Thank you for your contribution to WebhookX!

Stay Ahead

Star WebhookX on GitHub for instant updates on new releases.

star

License

WebhookX is under the Apache 2.0 license. See the LICENSE file for details.