Repository files navigation

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

• Introducing WebAssembly Plugin
• Function: A Way of Handling Webhook Verification Chaos

• Admin API: Expose a RESTful API on port:8080 for managing WebhookX entities.
• Retries: Automatically retry unsuccessful deliveries with configurable delays.
• Fan out: Route events to multiple endpoints based on the event type.
• Rate Limiting: Protect the gateway ingestion and delivery endpoints from overload.
• Declarative configuration: Manage WebhookX through declarative configuration files to achieve GitOps/DevOps workflows.
• Multi tenancy: Multiple workspaces. Each workspace provides the isolation of configuration entities.
• Plugins: Extend functionality via inbound and outbound plugins.
  • webhookx-signature: Sign outbound requests with HMAC(SHA-256) by addingWebhookx-Signature andWebhookx-Timestamp headers.
  • wasm: Transform outbound requests using high-level languages such as AssemblyScript, Rust or TinyGo. Seeplugin/wasm.
  • function: Customize inbound behavior with JavaScript, e.g. signature verification or request body transformation.
• Observability: OpenTelemetry metrics and tracing for monitoring and troubleshooting.

WebhookX binary provides you both Server and CLI command.

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

Download the binary distribution onreleases.

Thedocker-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:8080

HTTP/1.1 200 OKContent-Type: application/json; charset=utf-8Server: WebhookX/0.9.0{"version":"0.9.0","message":"Welcome to WebhookX","configuration": {}}

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

You may need to install CLIwebhookx first, seeInstallation.

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.

The Ingestion is exposed on port:8081

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

We sent acharge.succeeded event includingdata to WebhookX, and it will be routed and delivered to endpoints that are defined in thewebhookx.sample.ymlfile.

The Admin is exposed on port:8080

Let's make a request to retrieve the attempt list

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

{"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 asrequest.headers,request.body,response.headers, andresponse.body, try

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

{"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, seeopenapi.webhookx.io.

Usage:  webhookx [command]Available Commands:  admin       Admin commands  completion  Generate the autocompletion script for the specified shell  help        Help about any command  migrations    start       Start server  version     Print the versionFlags:  -h, --help      help for webhookx      --verbose   Verbose logging.Use "webhookx [command] --help" for more information about a command.

• CLI Reference

Requires the following runtime dependencies to work:

• PostgreSQL(>=13): Lower versions of PostgreSQL may work, but have not been fully tested.
• Redis(>=6.2): Requires minimum version 6.2.

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

The public API will strictly follow semantic versioning afterv1.0.0.

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!

Star WebhookX on GitHub for instant updates on new releases.

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