WebhookX: The Next-Generation Webhooks Gateway for Event Delivery

Introduction

WebhookX is an open-source, next-generation webhook gateway built in Go, designed to manage the complexities of receiving, validating, transforming, and delivering events at scale. It provides a robust and reliable solution for handling webhooks in cloud-native environments, ensuring your event-driven architectures run smoothly.

Installation

The WebhookX binary includes both server and CLI commands.

macOS

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

Linux | Windows

Download the binary distribution from the official releases page.

Examples

This quick start guide demonstrates how to get WebhookX running with Docker Compose and interact with it. For production deployments, refer to the official documentation.

1. Start WebhookX using Docker Compose

The docker-compose.yml provides a simple all-in-one (standalone) deployment for a 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, verify with a simple curl command:

curl http://localhost:9601

You should see an HTTP 200 response similar to:

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

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

2. Configure entities

Use a sample declarative configuration webhookx.sample.yml for this quick start. You may need to install the webhookx CLI first.

webhookx admin sync webhookx.sample.yml

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

3. Send events

The Ingestion API is exposed on port :9600.

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

This sends a charge.succeeded event, which WebhookX will route to endpoints defined in your configuration.

4. Inspect delivery results

Attempt objects represent delivery results and include inspection details. The Admin API is exposed on port :9601.

Retrieve the attempt list:

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

Example 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 request.headers, request.body, response.headers, and response.body for a specific attempt (e.g., 338lax8Xe774EhimzBukip37Zne), use:

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

Example 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/{version}",
      "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/{version}\", \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
}

Why Use WebhookX?

Reliable Delivery: Ensures events are delivered with automatic retries and configurable delays, minimizing data loss.
Scalability and Fan-out: Routes events to multiple endpoints based on event type, supporting complex event distribution patterns.
Rate Limiting: Protects both ingestion and delivery mechanisms from overload, maintaining system stability.
Declarative Configuration: Utilizes GitOps-friendly configuration files for easy management and version control.
Extensibility with Plugins: Supports extensible inbound and outbound processing through a variety of built-in plugins (e.g., webhookx-signature, wasm for transformations, function for custom logic, event-validation, and security plugins).
Observability: Integrates with OpenTelemetry for metrics and tracing, providing deep insights into event flow.
Secret Management: Allows referencing secrets from external providers, enhancing security.
Multi-tenancy: Provides workspace isolation for configuration entities, suitable for multi-tenant environments.