Octokit.Webhooks

Libraries to handle GitHub Webhooks in .NET applications.

Usage

ASP.NET Core

1. dotnet add package Octokit.Webhooks.AspNetCore

2. Create a class that derives from WebhookEventProcessor and override any of the virtual methods to handle webhooks from GitHub. For example, to handle Pull Request webhooks:

   public sealed class MyWebhookEventProcessor : WebhookEventProcessor
   {
       protected override ValueTask ProcessPullRequestWebhookAsync(
           WebhookHeaders headers,
           PullRequestEvent pullRequestEvent,
           PullRequestAction action,
           CancellationToken cancellationToken = default)
       {
           ...
       }
   }
   

3. Register your implementation of WebhookEventProcessor:

   builder.Services.AddSingleton<WebhookEventProcessor, MyWebhookEventProcessor>();
   

4. Map the webhook endpoint:

   app.UseEndpoints(endpoints =>
   {
       ...
       endpoints.MapGitHubWebhooks();
       ...
   });
   

MapGitHubWebhooks() takes two optional parameters:

• path. Defaults to /api/github/webhooks, the URL of the endpoint to use for GitHub.
• secret. The secret you have configured in GitHub, if you have set this up.

By default, exceptions thrown while processing a webhook are logged and return HTTP 500. Configure GitHubWebhookOptions.ExceptionHandler to handle specific exceptions and control the response:

builder.Services.Configure<GitHubWebhookOptions>(options =>
{
    options.ExceptionHandler = (exception, context) =>
    {
        if (exception is JsonException)
        {
            context.Response.StatusCode = StatusCodes.Status400BadRequest;
            return ValueTask.FromResult(true);
        }

        return ValueTask.FromResult(false);
    };
});

Returning true means the callback has completed the response. Returning false uses the default HTTP 500 behavior.

Azure Functions

NOTE: Support is only provided for isolated process Azure Functions.

1. dotnet add package Octokit.Webhooks.AzureFunctions

2. Create a class that derives from WebhookEventProcessor and override any of the virtual methods to handle webhooks from GitHub. For example, to handle Pull Request webhooks:

   public sealed class MyWebhookEventProcessor : WebhookEventProcessor
   {
       protected override ValueTask ProcessPullRequestWebhookAsync(
           WebhookHeaders headers,
           PullRequestEvent pullRequestEvent,
           PullRequestAction action,
           CancellationToken cancellationToken = default)
       {
           ...
       }
   }
   

3. Register your implementation of WebhookEventProcessor and configure the webhook function:

   var builder = FunctionsApplication.CreateBuilder(args);
   
   builder.Services.AddSingleton<WebhookEventProcessor, MyWebhookEventProcessor>();
   builder.ConfigureGitHubWebhooks();
   
   builder.Build().Run();
   

ConfigureGitHubWebhooks has two overloads:

• ConfigureGitHubWebhooks(string? secret = null). Pass the secret you have configured in GitHub, if you have set this up.
• ConfigureGitHubWebhooks(Func<IConfiguration, string> configure). Resolve the secret from configuration at runtime.

The function is available on the /api/github/webhooks endpoint.

Thanks

• octokit/webhooks
• terrajobst/Terrajobst.GitHubEvents
• Dotnet-Boxed/Templates

License

All packages in this repository are licensed under the MIT license.