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.

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

The Problem with Webhooks

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

1. Signature Verification: Each provider (Stripe, GitHub, Twilio) uses different HMAC algorithms
2. Reliability: Network failures require intelligent retry mechanisms
3. Observability: Debugging failed webhooks can be time-consuming
4. Multi-System Coordination: Fan-out to multiple targets with routing rules
5. 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

1. Ingest: Webhook received at /webhooks/:endpointId
2. Verify: HMAC signature validation per provider
3. Store: Event persisted to database with full payload
4. Route: Apply routing rules to determine target endpoints
5. Deliver: Fan-out to multiple targets with retry logic
6. 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

Target Management

Event Management

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:

1. Real-time Monitoring: Live updates via SignalR
2. Payload Inspection: Syntax-highlighted JSON viewing
3. Event Replay: One-click re-delivery of failed events
4. Endpoint Management: Create, update, delete endpoints and targets
5. Routing Rules: Visual rule builder with JSON path support
6. 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:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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.

Key Takeaways

1. Modern Stack: ASP.NET Core 8, React 19, latest technologies
2. Self-Hosted: Complete control without vendor lock-in
3. Open Source: MIT license, community-driven development

Next Steps

1. Try it out: Clone the repo and run locally
2. Star the project: Show support on GitHub
3. Contribute: Help build the future of webhook management
4. Share: Spread the word in .NET communities

Ready to get started? Visit the GitHub repository and start managing your webhooks like a pro!

For more .NET development content, follow me on LinkedIn.

Built with ❤️ by Vikrant Bagal