Vikrant Bagal

Posted on Apr 23

Introducing WebhookRelay: A Modern .NET Open Source Webhook Management Platform

#dotnet #react #webdev #webhook

Building a webhook relay infrastructure with ASP.NET Core 8 and React 19

Introduction

I'm excited to announce WebhookRelay — a self-hosted, open-source webhook management platform built specifically for the (beta) .NET ecosystem. After years of working with webhook integrations and seeing the limitations of existing solutions, I set out to create a modern, alternative that leverages the latest .NET technologies while providing complete control and flexibility.

The Problem with Webhooks

Webhooks are the backbone of modern integrations, but managing them at scale presents several challenges:

Signature Verification: Each provider (Stripe, GitHub, Twilio) uses different HMAC algorithms
Reliability: Network failures require intelligent retry mechanisms
Observability: Debugging failed webhooks can be time-consuming
Multi-System Coordination: Fan-out to multiple targets with routing rules
Vendor Lock-in: Commercial solutions can be expensive and inflexible

The Solution: WebhookRelay

WebhookRelay addresses these challenges with a comprehensive feature set:

Core Features

✅ Multi-Provider Ingestion

Stripe: Automatic signature verification via Stripe-Signature header
GitHub: X-Hub-Signature-256 verification out of the box
Twilio: Built-in support for Twilio webhooks
Generic: Custom HMAC-SHA256 verification for any provider

✅ Security First

Constant-time HMAC comparison to prevent timing attacks
Complete audit log of all inbound requests (including rejected events)
Per-endpoint secret management

✅ Intelligent Delivery

Fan-out: Forward one webhook to multiple target URLs simultaneously
Routing Rules: JSON path conditions (equals, contains, starts_with, exists, etc.)
Automatic Retries: Exponential backoff with configurable max attempts
Dead-letter Queue: Failed events stored for manual inspection

✅ Event Management

Duplicate Detection: Provider event IDs deduplicated per endpoint
Event Replay: Re-deliver any stored event on demand
Real-time Dashboard: Live updates via SignalR with syntax-highlighted payloads

Technology Stack

WebhookRelay leverages cutting-edge .NET and frontend technologies:

Backend

ASP.NET Core 8 Web API
Entity Framework Core 8 for data access
System.Threading.Channels for high-performance in-process queuing
Serilog for structured logging

Frontend

React 19 with Vite 8
TypeScript for type safety
shadcn/ui + Tailwind CSS for modern UI
TanStack Query v5 for server state management
React Router v7 for navigation
React Hook Form + Zod for forms

Real-time Features

ASP.NET Core SignalR for live dashboard updates
WebSocket connections for instant event notifications

Architecture Overview

Clean Architecture

WebhookRelay.sln
├── src/
│   ├── WebhookRelay.Api/          # ASP.NET Core Web API + background workers
│   ├── WebhookRelay.Core/         # Domain entities, interfaces (no external deps)
│   ├── WebhookRelay.Infrastructure/ # EF Core, HTTP delivery, verifiers
│   └── WebhookRelay.Shared/       # DTOs shared between API and frontend
├── dashboard/                      # React 19 frontend
├── tests/                          # Comprehensive test suite
└── deploy/                         # Docker Compose deployment

Data Flow

Ingest: Webhook received at /webhooks/:endpointId
Verify: HMAC signature validation per provider
Store: Event persisted to database with full payload
Route: Apply routing rules to determine target endpoints
Deliver: Fan-out to multiple targets with retry logic
Monitor: Real-time dashboard updates via SignalR

Getting Started

Prerequisites

.NET 8 SDK
Node.js 22+

Quick Start

# Clone the repository
git clone https://github.com/vrbagal/webhook-relay.git
cd webhook-relay

# Start the API (uses SQLite by default)
cd src/WebhookRelay.Api
dotnet run
# API available at https://localhost:5001

# Start the dashboard
cd dashboard
npm install
npm run dev
# Dashboard available at http://localhost:3000

Configuration

The project supports multiple databases out of the box:

SQLite (Default - Zero Config)

{
  "DatabaseProvider": "Sqlite",
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=webhookrelay.db"
  }
}

SQL Server

{
  "DatabaseProvider": "SqlServer",
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=WebhookRelay;Trusted_Connection=True;"
  }
}

PostgreSQL

{
  "DatabaseProvider": "PostgreSQL",
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Database=webhookrelay;Username=postgres;Password=yourpassword"
  }
}

Docker Deployment

cd deploy
docker compose up --build

Services started:

api: ASP.NET Core API on port 5000
dashboard: React app served via nginx on port 80
db: SQL Server 2022 (when using SqlServer profile)

Using WebhookRelay

Sending Webhooks

# Compute signature
SECRET="your-signing-secret"
PAYLOAD='{"event":"payment.completed","amount":100}'
SIG=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

# Send webhook
curl -X POST https://localhost:5001/webhooks/<endpoint-id> \
  -H "Content-Type: application/json" \
  -H "x-webhook-signature: sha256=$SIG" \
  -H "x-webhook-event: payment.completed" \
  -H "x-webhook-id: evt-$(date +%s)" \
  -d "$PAYLOAD"

Provider-Specific Sending

Stripe: Just send the original Stripe webhook — it's automatically verified
GitHub: Send as-is — the X-Hub-Signature-256 header is verified automatically

API Endpoints

Endpoint Management

Method	Path	Description
GET	`/api/endpoints`	List all endpoints
POST	`/api/endpoints`	Create endpoint
GET	`/api/endpoints/:id`	Get endpoint details
PUT	`/api/endpoints/:id`	Update endpoint
DELETE	`/api/endpoints/:id`	Delete endpoint

Target Management

Method	Path	Description
POST	`/api/endpoints/:id/targets`	Add delivery target
DELETE	`/api/endpoints/:id/targets/:targetId`	Remove target

Event Management

Method	Path	Description
GET	`/api/events`	List events (paginated, filterable)
GET	`/api/events/:id`	Get event with delivery attempts
POST	`/api/events/:id/replay`	Replay event

Real-World Use Cases

E-commerce Integration

// Stripe webhook handler with routing rules
{
  "endpoint": "stripe-payments",
  "targets": [
    {
      "url": "https://api.myapp.com/payments",
      "rules": [{ "path": "$.type", "operator": "equals", "value": "payment_intent.succeeded" }]
    },
    {
      "url": "https://analytics.myapp.com/events",
      "rules": [{ "path": "$.type", "operator": "contains", "value": "payment" }]
    }
  ]
}

GitHub Automation

// GitHub webhook fan-out for CI/CD
{
  "endpoint": "github-repo",
  "targets": [
    { "url": "https://ci.example.com/webhook" },
    { "url": "https://notifications.example.com/github" },
    { "url": "https://analytics.example.com/events" }
  ]
}

Multi-System Coordination

CRM Integration: Forward webhooks to Salesforce, HubSpot, and custom systems
Notification Systems: Send to Slack, email, and SMS simultaneously
Analytics: Route events to multiple analytics platforms

Dashboard Features

The React dashboard provides comprehensive webhook management:

Real-time Monitoring: Live updates via SignalR
Payload Inspection: Syntax-highlighted JSON viewing
Event Replay: One-click re-delivery of failed events
Endpoint Management: Create, update, delete endpoints and targets
Routing Rules: Visual rule builder with JSON path support
Delivery Analytics: Success/failure rates and retry statistics

Performance & Scalability

In-Process Queue

WebhookRelay uses System.Threading.Channels for high-performance, in-process queueing:

Zero external dependencies
Excellent performance characteristics
Built-in backpressure handling

Database Flexibility

SQLite: Perfect for development and small deployments
SQL Server: Enterprise-grade with full transaction support
PostgreSQL: Open-source with advanced features

Deployment Options

Self-hosted: Complete control on your infrastructure
Docker: Easy containerization and orchestration
Cloud: Deploy to Azure, AWS, or any cloud provider

Security Considerations

HMAC Verification

Each provider's signature algorithm is implemented exactly:

Stripe: Stripe-Signature header with timestamp and signature
GitHub: X-Hub-Signature-256 with HMAC-SHA256
Generic: Custom x-webhook-signature header

Constant-Time Comparison

All signature verifications use constant-time comparison to prevent timing attacks.

Secret Management

Per-endpoint secret configuration
Environment variable support
Azure Key Vault integration ready

Testing Strategy

Unit Tests

Core business logic
Signature verification algorithms
Routing rule evaluation

Integration Tests

API endpoints with WebApplicationFactory
Database operations
External HTTP delivery

End-to-End Tests

Full webhook flow from ingestion to delivery
Dashboard functionality
Docker deployment

Future Roadmap

Immediate (v1.1)

[ ] Enhanced documentation with tutorials
[ ] SDK for popular languages (Python, Node.js, Go)
[ ] Plugin system for custom providers
[ ] Advanced analytics and reporting

Medium-term (v1.2)

[ ] Multi-tenancy support
[ ] Webhook transformation (modify payload before delivery)
[ ] Advanced routing with regex support
[ ] Rate limiting per endpoint

Long-term (v2.0)

[ ] Managed cloud service option
[ ] Marketplace for pre-built integrations
[ ] Enterprise features (SSO, audit logs, SLA)
[ ] Machine learning for anomaly detection

Contributing

WebhookRelay is an open-source project and welcomes contributions:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Areas for Contribution

Documentation: Tutorials, API docs, deployment guides
Testing: Unit tests, integration tests, E2E tests
Features: New providers, advanced routing, analytics
UI/UX: Dashboard improvements, accessibility

Conclusion

WebhookRelay represents a modern approach to webhook management, built from the ground up for .NET developers who want complete control over their integration infrastructure. Whether you're building a multi-tenant SaaS application, integrating multiple payment providers, or coordinating complex business workflows, WebhookRelay provides the foundation you need.