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:

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