Quick Start

Docker Compose (recommended)

git clone https://github.com/voyvodka/webhook-engine.git
cd webhook-engine
docker compose -f docker/docker-compose.yml up -d

The app starts on http://localhost:5100. Dashboard login: admin@example.com / changeme.

Local Development

Prerequisites: .NET 10 SDK, PostgreSQL 17+, Node.js 20+, Yarn

1. Start PostgreSQL (or use the dev compose file):

docker compose -f docker/docker-compose.dev.yml up -d

2. Configure connection string in src/WebhookEngine.API/appsettings.json:

{
  "ConnectionStrings": {
    "Default": "Host=localhost;Port=5432;Database=webhookengine;Username=webhookengine;Password=webhookengine"
  }
}

3. Run the backend (migrations auto-apply on startup):

dotnet run --project src/WebhookEngine.API

The API starts on http://localhost:5128.

4. Run the dashboard (optional, for frontend development):

cd src/dashboard
yarn install
yarn dev

Dashboard dev server runs on http://localhost:5173 with API proxy to localhost:5128.

Documentation

• Getting Started — from zero to first webhook
• Self-Hosting Guide — production deployment and operations
• Release Guide — Docker Hub and NuGet publishing flow
• Launch Checklist — final pre-launch and go-live tracking
• API Reference — full endpoint documentation
• Architecture — system design and component overview
• Database — schema and PostgreSQL notes
• Contributing — local setup and pull request workflow
• Changelog — notable project changes
• Samples guide, Sample Sender, and Sample Receiver
• Signature verification helpers for C#, TypeScript, and Python

Architecture

                    +---------------------------+
                    |    ASP.NET Core Host       |
                    |                           |
   HTTP requests -> | Controllers (REST API)    |
                    | Middleware (auth, logging) |
                    | Static files (React SPA)  |
                    | SignalR Hub               |
                    |                           |
                    | Background Workers:       |
                    |  - DeliveryWorker         |
                    |  - RetryScheduler         |
                    |  - CircuitBreakerWorker   |
                    |  - StaleLockRecovery      |
                    |  - RetentionCleanup       |
                    +------------+--------------+
                                 |
                                 v
                    +---------------------------+
                    |     PostgreSQL 17+         |
                    |  - Data storage            |
                    |  - Job queue (SKIP LOCKED) |
                    +---------------------------+

Solution Structure

src/
  WebhookEngine.Core/            # Domain: entities, enums, interfaces, options
  WebhookEngine.Infrastructure/   # EF Core, PostgreSQL queue, repositories, services
  WebhookEngine.Application/      # DI registration (CQRS scaffold, not yet implemented)
  WebhookEngine.Worker/           # Background services (delivery, retry, circuit breaker)
  WebhookEngine.API/              # ASP.NET Core host, controllers, middleware
  WebhookEngine.Sdk/              # .NET client SDK
  dashboard/                      # React SPA (Vite + TypeScript)
tests/
  WebhookEngine.Core.Tests/
  WebhookEngine.Infrastructure.Tests/
  WebhookEngine.Application.Tests/
  WebhookEngine.API.Tests/
  WebhookEngine.Worker.Tests/

API Overview

Base URL: /api/v1/

Authentication

• API key (for programmatic access): Authorization: Bearer whe_{appId}_{random}
• Cookie auth (for dashboard): POST /api/v1/auth/login

Endpoints

Send a Message

curl -X POST http://localhost:5128/api/v1/messages \
  -H "Authorization: Bearer whe_abc123_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "order.created",
    "payload": {"orderId": 42, "amount": 99.99},
    "idempotencyKey": "order-42"
  }'

Response:

{
  "data": {
    "messageIds": ["msg_abc123..."],
    "endpointCount": 2,
    "eventType": "order.created"
  },
  "meta": { "requestId": "req_..." }
}

.NET SDK

using WebhookEngine.Sdk;

using var client = new WebhookEngineClient("whe_abc_your-api-key", "http://localhost:5128");

await client.Messages.SendAsync(new SendMessageRequest
{
    EventType = "order.created",
    Payload = new { orderId = 42, amount = 99.99 },
    IdempotencyKey = "order-42"
});

Webhook Signature Verification

WebhookEngine signs every delivery with HMAC-SHA256 following the Standard Webhooks spec. Receivers should verify signatures like this:

# Python example
import hmac, hashlib, base64

def verify_webhook(body: bytes, secret: str, headers: dict) -> bool:
    msg_id = headers["webhook-id"]
    timestamp = headers["webhook-timestamp"]
    signature = headers["webhook-signature"]

    payload = f"{msg_id}.{timestamp}.{body.decode()}"
    secret_bytes = base64.b64decode(secret)
    expected = hmac.new(secret_bytes, payload.encode(), hashlib.sha256).digest()
    expected_sig = f"v1,{base64.b64encode(expected).decode()}"

    return hmac.compare_digest(signature, expected_sig)

Configuration

All configuration is via appsettings.json or environment variables (double-underscore notation):

Build & Test

# Build
dotnet build WebhookEngine.sln

# Run all tests (106 tests)
dotnet test WebhookEngine.sln

# Run specific test project
dotnet test tests/WebhookEngine.Core.Tests

# Run tests matching a pattern
dotnet test --filter "DisplayName~HmacSigning"

# Dashboard build
cd src/dashboard && yarn install && yarn build

Docker

# Production
docker compose -f docker/docker-compose.yml up -d

# Development (starts PostgreSQL only, run backend separately)
docker compose -f docker/docker-compose.dev.yml up -d
dotnet run --project src/WebhookEngine.API

Prometheus Metrics

WebhookEngine exposes Prometheus metrics at GET /metrics. No authentication required.

curl http://localhost:5128/metrics

Custom Metrics

Built-in Metrics

ASP.NET Core request metrics and .NET runtime metrics (GC, thread pool, etc.) are also included automatically.

Prometheus Scrape Config

# prometheus.yml
scrape_configs:
  - job_name: webhookengine
    scrape_interval: 15s
    static_configs:
      - targets: ["localhost:5128"]

Message Lifecycle

  Send API call
       |
       v
  [Pending] --dequeue--> [Sending] --success--> [Delivered]
       ^                     |
       |                     | failure
       |                     v
       +--retry-schedule-- [Failed] --max-retries--> [DeadLetter]

• Pending: Queued for delivery
• Sending: Locked by a worker, in-flight
• Delivered: Successfully delivered (HTTP 2xx)
• Failed: Delivery failed, scheduled for retry
• DeadLetter: All retry attempts exhausted

License

MIT