Add EventNotificationHandler

[xavdid-stripe]

Why?

We've been designing a streamlined approach to handling incoming events that is easy to get right and hard to get wrong. This PR has the initial implementation of this new system.

The only other pending item is to add a method to allow handling a webhook without verifying the signature. This is good for testing and for Event Bridge, which doesn't use the signature-based verification. Otherwise, this is ready for review.

What?

• add EventHandler class
• add event handler constructor on StripeClient
• add tests
• add method for changing the stripe context on a client

Example usage

[Route("api/[controller]")]
[ApiController]
public class EventNotificationWebhookHandler : ControllerBase
{
    private readonly StripeClient client;
    private readonly StripeEventNotificationHandler handler;

    public EventNotificationWebhookHandler()
    {
        client = new StripeClient(Environment.GetEnvironmentVariable("STRIPE_API_KEY"));
        handler = client.NotificationHandler(Environment.GetEnvironmentVariable("WEBHOOK_SECRET") ?? string.Empty, FallbackCallback);

        // register handlers
        handler.V1BillingMeterErrorReportTriggered += HandleBillingMeterErrorReportTriggeredEventNotification;
    }

    private void HandleBillingMeterErrorReportTriggeredEventNotification(object sender, Stripe.StripeEventNotificationEventArgs<Stripe.Events.V1BillingMeterErrorReportTriggeredEventNotification> e)
    {
        var meter = e.EventNotification.FetchRelatedObject();
        Console.WriteLine($"Meter {meter.DisplayName} had an error");
    }

    private void FallbackCallback(object sender, Stripe.StripeUnhandledEventNotificationEventArgs e)
    {
        Console.WriteLine($"Received unhandled event notification type: {e.EventNotification.Type}");
    }

    [HttpPost]
    public async Task<IActionResult> Index()
    {
        var json = await new StreamReader(HttpContext.Request.Body).ReadToEndAsync();
        handler.Handle(json, Request.Headers["Stripe-Signature"]);
        return null;
    }
}

See Also

• DEVSDK-2822
• ⚠️ Add strongly typed EventNotifications #3168

[jar-stripe]

Not sure if the comment should go here or in your doc, but HandleUnhandledError seems like the wrong name in your example. That's just HandleUnhandledEventNotification, right?

[jar-stripe]

will this ever get constructed outside of our SDK code? If not, I would consider changing this constructor to be internal

[xavdid-stripe]

Wouldn't users need it for tests? Like, if they write their function and want to test it in isolation, that function takes these args and they'd nee to be able to construct it?

[jar-stripe]

Took a pass thru, it looks largely good (the names are pretty long and I left a comment in your naming doc), but I have concerns about StripeClient/ApiRequestor reuse when you swap in and out the StripeContext

[jar-stripe]

Also, we should consider adding the example from the PR description as an actual example in the project, so folks can see how to use this from code they can easily find.

[cla-assistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[xavdid-stripe]

ok @jar-stripe this is ready for re-review!

My biggest open question is about supporting async - in Node, all of the callbacks return promises for easier integration with making stripe client calls. In python we haven't added support for async (yet) since i'm not positive how we'll do it. For dotnet, I know users can call async functions syncronously. So, is it worth having Handle be async and all of the callbacks be too?

Also re: naming. Dotnet having a built-in event thing called a "handler" (that other languages call a "callback") muddles our naming a bit. Is it worth diverging from the other languages here for consistency? Basically, the fill-in-the-blank exercise we did for the other languages is:

A user instantiates a _____, registers 1+ ______, and then invokes that [1st blank] from their (framework-specific) webhook endpoint.

Today, it's

A user instantiates an event (notification) handler, registers 1+ callback functions, and then invokes that handler from their (framework-specific) webhook endpoint.

But should dotnet be different?

[xavdid-stripe]

ignoring CLA check (??) and merging