StandardWebhooks

Implementation of Standard Webhooks for .NET Core

StandardWebhooks is an implementation of the Standard Webhooks specification initiated by Svix and supported by other industry participants including Zapier, Twilio, ngrok and Kong.

This repo extends the C# reference implementation, providing a maintained (nuget package) along with some helpful features for ASP.NET Core developers.

It is supported on all current .NET Core platforms (.NET 6.0, .NET 8.0).

Generating HttpContent for a Webhook

var myEntity = new MyEntity
{
    Id = 1,
    Name = "Test Entity",
    Description = "This is a test entity"
};

var webhook = new StandardWebhook(WEBHOOK_SIGNING_KEY);

var sendingTime = DateTimeOffset.UtcNow;

var webhookContent = webhook.MakeHttpContent(myEntity, DEFAULT_MSG_ID, sendingTime);

Verifying a Webhook signature

// Assumes messageBody contains string representation of message content
// and request is an HttpRequest with the Standard Webhooks headers set

var webhook = new StandardWebhook(WEBHOOK_SIGNING_KEY);

// Throws WebhookVerificationException if verification fails
webhook.Verify(messageBody, request.Headers);

Factory Pattern

The library provides IStandardWebhookFactory and its implementation StandardWebhookFactory which are intended for use in ASP.NET DI scenarios. Usage:

// In Program.cs, or wherever services are configured.  Optionally WebhookConfigurationOptions can be
// provided as a second parameter to configure which header names to use.

services.AddSingleton<IStandardWebhookFactory>(sp =>
    new StandardWebhookFactory(WEBHOOK_SIGNING_KEY));

// In method, add IStandardWebhookFactory as an injected parameter and then:
var webhook = webhookFactory.CreateWebhook();

Standard Configurations

Two standard WebhookConfigurationOptions configurations are provided as static instances, WebhookConfigurationOptions.StandardWebhooks and WebhookConfigurationOptions.Svix, the former for the HTTP headers as described in the Standard Webhooks specification and the latter for the headers used by Svix. The default configuration if no options are supplied is WebhookConfigurationOptions.StandardWebhooks.

Questions and Answers

Please raise any issues or questions via the Issues page on GitHub.

Roadmap

Currently the library doesn't provide any support for sending messages, beyond the ability to create an HttpContent instance from the message payload. The plan is to extent the library to support message transmission using HttpClient/IHttpClientFactory, leveraging the retry capabilites of the Polly package.

Acknowledgements

This project leverages the work of the Standard Webhooks project, published on Github in the standard-webhooks repository. Specifically it builds upon the C# reference implementation.

License

This project is licensed under the MIT License.