Authlink.Webhooks.AspNetCore 1.0.0

Authlink.Webhooks.AspNetCore

ASP.NET Core integration for Authlink webhook handling with automatic signature validation and model binding.

Installation

dotnet add package Authlink.Webhooks.AspNetCore

Quick Start

Register services in your application:

using Authlink.Webhooks.AspNetCore.Extensions;

// In Program.cs
builder.Services.AddAuthlinkWebhooksAspNetCore(options =>
{
    options.SecretConfigKey = "Webhooks:RegistrationSecret";
});

builder.Services.AddControllers()
    .AddWebhookModelBinders();

Usage

Using Model Binders with Action Filter

The simplest approach combines automatic model binding with signature validation:

using Authlink.Webhooks.AspNetCore.Filters;
using Authlink.Webhooks.Core.Payloads;
using Authlink.Webhooks.Core.Responses;

[ApiController]
[Route("webhooks")]
public class WebhooksController : ControllerBase
{
    [HttpPost("registration")]
    [ValidateWebhookSignature(SecretConfigKey = "Webhooks:Secret")]
    public IActionResult HandleRegistrationWebhook(WebhookEvent<RegistrationCompletingPayload> webhook)
    {
        // Signature has already been validated
        // Model binder automatically parses the webhook event
        var payload = webhook.Data;

        // Process the webhook...

        return Ok(WebhookResponseBuilder.Approve());
    }
}

Using the Action Filter Attribute

The [ValidateWebhookSignature] attribute validates signatures before your action executes:

using Authlink.Webhooks.AspNetCore.Filters;
using Authlink.Webhooks.Core.Payloads;
using Authlink.Webhooks.Core.Responses;

[ApiController]
[Route("webhooks")]
public class WebhooksController : ControllerBase
{
    [HttpPost("registration")]
    [ValidateWebhookSignature(SecretConfigKey = "Webhooks:Secret")]
    public IActionResult HandleRegistrationWebhook(
        [FromBody] WebhookEvent<RegistrationCompletingPayload> webhook)
    {
        // Signature has already been validated
        // Process the webhook...

        return Ok(WebhookResponseBuilder.Approve());
    }
}

Customizing Header Names

[ValidateWebhookSignature(
    SecretConfigKey = "Webhooks:Secret",
    SignatureHeader = "X-Custom-Signature",
    TimestampHeader = "X-Custom-Timestamp")]
public IActionResult HandleWebhook([FromBody] WebhookEvent<RegistrationCompletingPayload> webhook)
{
    return Ok(WebhookResponseBuilder.Approve());
}

Using Middleware for Path-Based Validation

For validating all webhooks on specific paths:

using Authlink.Webhooks.AspNetCore.Extensions;

// In Program.cs
builder.Services.AddAuthlinkWebhooksAspNetCore(options =>
{
    options.WebhookPaths = ["/webhooks", "/api/webhooks"];
    options.Secret = builder.Configuration["Webhooks:Secret"];
});

var app = builder.Build();

// Add middleware before routing
app.UseWebhookSignatureValidation();

app.MapControllers();

Combining Approaches

You can use both approaches together:

• Middleware for general webhook paths
• Attribute for specific endpoints that need different configuration

Configuration

WebhookOptions

Configure webhooks using the options pattern:

builder.Services.AddAuthlinkWebhooksAspNetCore(options =>
{
    // Option 1: Specify secret directly
    options.Secret = "your-secret";

    // Option 2: Specify configuration key (default: "Webhooks:Secret")
    options.SecretConfigKey = "Webhooks:RegistrationSecret";

    // Customize headers
    options.SignatureHeader = "X-Authlink-Signature";
    options.TimestampHeader = "X-Authlink-Timestamp";

    // Configure paths for middleware
    options.WebhookPaths = ["/webhooks", "/api/webhooks"];
});

Configuration File

Add your webhook secret to appsettings.json:

{
  "Webhooks": {
    "Secret": "your-webhook-secret-here"
  }
}

Error Responses

When signature validation fails, the filter/middleware returns:

• 401 Unauthorized with { "error": "Missing webhook signature" } if the signature header is missing
• 401 Unauthorized with { "error": "Invalid webhook signature" } if the signature is invalid

When model binding fails:

• 400 Bad Request with model state errors describing the parsing failure

Security Features

• Automatic request body buffering for signature validation
• Support for timestamp-based replay attack prevention
• Constant-time signature comparison

Related Packages

• Authlink.Webhooks - Core webhook functionality
• Authlink.Webhooks.Core - Core types and interfaces