Custom Azure Event Grid event handling with .NET Core WebHook

Custom Azure Event Grid Event Handling with .NET Core WebHook

Some background first

In todays Cloud first world Event Driven Architecture  (EDA) and reactive programming are gaining a lot of traction in Microservices architecture design and development paradigm. In the event driven architecture scenario WebHook plays a huge role doing various stuffs in a reactive manner with Pub-Sub model.

When a HTTP endpoint responds to a request (instruction) and does some stuffs like GET, POST, DELETE then we can safely call it API,  but when a HTTP endpoint responds on it’s own when certain event occurs then we can call it a WebHook. For a WebHook to respond to certain events it has to subscribe to an event publisher with it’s HTTP endpoint URL. In the current context WebHook is the subscriber of Azure Event Grid topic.

To understand and translate “Custom Azure Event Grid Event Handling with .NET Core WebHook” concept into action, I am going to briefly walk you through the following 
  1. Create a HTTP endpoint in a .NET Core WEB API app.
  2. Make necessary changes to the endpoint code to make it a WebHook.
  3. Subscription validation to register this endpoint to Event Grid topic.
  4. Handling Custom events.
  5. Which scenario is best for WebHook etc.

Get into action

Creating HTTP Endpoint
Create a new .NET Core Web API project in Visual Studio 

A .NET Core API project can be created in Visual Studio with the following steps –
From File menu – File >> New >> Select .NET Core under Visual C# >> Select ASP.NET Core Web Application

Provide a name  the project >> Ok >> Select .NET Core 2.0 from the dropdown menu in the wizard  >> Select API and >> Ok

Add a new Controller to the project

A HTTP endpoint, which is a WebHook must receive events in HTTP POST only. We need to create a new controller with a POST method to receive events.

In this example, the controller name is EventGridEventHandlerController and the Post method would look like this

The method body may look a bit confusing at this moment, but in next section it will be clarified.

Subscription Validation

A WebHook needs to be registered or subscribed to an event publisher. This WebHook that we are building here is going to receive events from Azure Event Grid. This WebHook endpoint URL needs to be subscribed to Azure Event Grid topic.

Not every HTTP endpoint can subscribe to Azure Event Grid topics. While subscribing to Azure Event Grid topic, Azure Event Grid sends a validation request to the subscribing URL endpoint with a validation code. If the endpoint echos back with the same Validation Code then only Event Grid accepts that endpoint URL as a valid endpoint for subscription.

While registering an endpoint URL to Event Grid topic it sends a message in following structure

If the registering endpoint responds (echos) back the ValidationResponse with the validationCode from subscription validation event  as below then only it gets registered.

It shows URL validation failure error if the validation code can’t be echoed back from the subscriber. Line 18 to 35 takes care of the event subscription validation in above controller’s Post method.

The execution flow is something like this – Event Grid posts a subscription validation event with EventType as “eventType”: “Microsoft.EventGrid.SubscriptionValidationEvent”  and validation code “validationCode”: “512d38b6-c7b8-40c8-89fe-f46f9e9622b6”.

This code checks whether the EventType is of Microsoft.EventGrid.SubscriptionValidationEvent(Line 24), if yes then it gets the ValidationCode from the request and echos back with ValidationResponse at Line 34.

Subscription to Azure Event Grid topic is onetime activity, and hence the code in if block will only be executed while subscribing the endpoint URL to the topic.

For all other event types it goes to the else block of the code. All custom event handling code needs to be in else block only.

Processing a Custom Azure Event Grid Event
An empty Azure Event Grid event schema looks like this

To prepare a custom event, CustomData needs to be injected in the EventGridEvent message schema. This contains  EventType, event Id, EventTime along with Data.

CustomEvent class structure and it’s corresponding JSON payload of this sample code looks like this, using which custom event will be generated.

This custom JSON payload will be processed at the else block of the code since the EventType is of ‘MyCustomEventType’ type.

Azure Event Grid Subscription

To subscribe to Azure Event Grid topic, ASP.NET Core API project with the above controller needs to be deployed to Azure accessible location. I prefer to deploy in Azure App Services. Once deployed, the deployed URL needs to be subscribed to the Event Grid topic.

An Event Grid Topic can receive multiple events and it can have multiple subscribers too. A subscribed endpoint needs to filter evens with EventType while subscribing to Event Topic. This allows a WebHook to respond to certain events only than to respond to all types of events of a event publisher.

To subscribe to an event topic – in Azure portal Create a new Event Topic subscription, Un-check ‘Subscribe all event types’ in Event Types section. Add Event Type as ‘MyCustomEventType‘. Select Endpoint type as Web Hook and select the deployed URL (https://{} as Endpoint and hit the Create button.

Once subscription is done you can try out this sample code to raise a custom event to Azure Event topic and expect EventGridEventHandler WebHook to respond to it.

When to use WebHook and what alternatives do we have?

Now that we have got some understanding of WebHook and it’s usage for Custom event handling, lets see whether WebHook is best suited for your scenario to handle Azure Event Grid Custom events or not.

Microsoft recommends usage of Serverless Azure Function for Event Grid event handling. In Azure Function V1 you can create a HTTP trigger. Register that Azure Function endpoint to respond to custom event grid events. Obviously it needs to validate the subscription validation.

Best and recommended way to respond to Azure Event Grid events is to use EventGridTrigger in Azure Function V2 (at the time of writing of this post Azure Function V2 is not GA). EventGridTrigger internally handles the SubscriptionValidation and you end up with writing only the code for necessary for custom event handling.

If you already have an up and running API app ( built in .NET Core or in .NET Framework), you do not want to create/ pay for a new Serverless Azure Function app then you just need to add a HTTP endpoint to your existing API app and use it as WebHook.

Many organization doesn’t feel comfortable in deploying softwares in Production which are not GA and in preview.  If this is true for you as well, then in this scenario you can’t use Azure Function V2. Custom WebHook or  Azure Function V1 HTTP trigger is right option for you.

Wrap up

In this article we have covered basic difference between API and WebHook, we have created a WebHook in .NET core, described how to handle Azure Event Grid Subscription validation, handling custom events and finally talked about some scenarios where a WebHook is useful than to it’s alternatives.

Now, the entire solution AzureEventGridHandler is hosted in GitHub. This shows four ways to interact with Azure Event Grid Custom Events.

  1. WebHook in .NET Core (which is this article is mostly about)
  2. WebHook in .NET framework,
  3. Using Azure Function V1 HTTP Trigger and finally
  4. Using Azure Function V2 Event Grid Trigger.
Just dive into it and start exploring event driven programming with and WebHooks Azure Functions.