Writing Senders

In Chapter 4, we discussed and walked through all the steps required to create a new WebHook receiver. Now think of a scenario, where you want to create your own sender so, others can create or consume the WebHook receiver for your sender. In this chapter, we will walk you through the process of creating your own sender step-by-step.

WebHook senders

Writing your own sender is slightly different from consuming a receiver; the process is outlined in the following sections.

Subscription

A WebHook sender application should provide an interface, an API, or some way for users to subscribe to the events and receive notifications. These events may vary from application to application. Let us say that we would like to create WebHooks senders for Docunate^TM—for this our events would be:

• Document added, updated, deleted
• Document keywords added, updated, deleted

Management

A WebHook sender application should be capable of managing all users/subscribers, including registered WebHooks by them. There should be a way to persist this information. Don’t let this statement sway your thoughts towards a database persistence—there is a way out, and we will be discussing that shortly.

Mapping

Subscribers and their subscriptions should be mapped in such a way that a particular event notification is sent to a subscriber who is registered for that event. In other words, if user A is subscribed for event the document:added, and user B is subscribed for the event keywords:added, the WebHook sender should send notifications to user A for document:added, and to user B for keywords:added.

Using ASP.NET WebHooks to create custom senders

It would be complex and require more effort than usual to implement everything from scratch. The managing of senders can also be sometimes painful. If we want to write our own senders from scratch, then we have to keep all these points (discussed in the preceding section) in mind, as ignoring these could make our life difficult. Thankfully, ASP.NET WebHooks provides a way to create your own senders and make your work very simple.

ASP.NET WebHooks provides us inherent support for registering subscribed events apart from managing and persisting subscription in Azure storage. More importantly, it provides us a means of handling errors and retrying notifications as many times as required. It also provides a means of maintaining queue and load balancing between sender and the receiver app. In short, ASP.NET WebHooks gives us pretty much everything we need to create our own sender.

Creating a sender depends on the nature of its application, so all senders will have some differences. For an example: Bitbucket sends notifications differently from GitHub notifications. The common denominator for any sender is event subscription, as every sender pushes notification for an event. In other words, both Bitbucket and GitHub send notifications, whenever a push event triggers (if someone has subscribed to these events, then they will get a notification for the same).

ASP.NET sample web app

In this section we will discuss a sample app meant to be our sender, which can be downloaded here. This sample application is meant to send notifications to subscribed users for preferred events. This app would also provide an interface to subscribe to all or specified events, so subscribers can receive notifications for those events. Our sample web application will have certain web APIs to perform specific tasks, and will expose all events so that subscribers can subscribe to all or specific events.

Tip: For more information on Web API, read ASP.NET Web API Succinctly.

Figure 31: Pictorial view Senders to Receiver

Sender applications can send event notifications to all the receivers that may have subscribed, at once. However, receivers may or may not subscribe for more than one event. Receivers will receive notifications for all the events they have subscribed. It works in a way similar to having one post resource of a Web API; the post resource returns back the data to the user as soon as a post request completes.

Scenarios for sending notifications

Here are few scenarios where we can treat notification differently:

Consider a scenario where all users or a group of users need event notifications for all or one of the subscribed events. In this likely scenario, it becomes the responsibility of the sender to manage it. Our sample app (sender) is capable doing this as well. In the coming sections, we will discuss what base framework or projects we require to work with this application.

Another important scenario is where an anonymous user needs to receive notifications for subscribed events by a group to which this user belongs. Internally, the application sends notifications to a group and not to the individual user. So it’s the responsibility of the subscribers to subscribe in such a way that whenever the receiver receives the notification, it will deliver it to all the group members. ASP.NET provides a way to send notifications to all users at once.

There could be times when we need to send notifications to all users except one or two in the group, or when the users are subscribed for a particular event only. In this scenario, ASP.NET helps us send notifications to all subscribers/users, and we can easily add simple logic to skip a particular user for notifications. We’d use something like: sendToAllUsers.where(s=> s.user != ‘userA’).

Figure 32: Pictorial view of sending notifications to limited number of users

Figure 32 is pictorial view for sending notifications to subscribed subscribers. Here, three subscribers are subscribed for the event document:created, but the sender is sending notifications to only Receiver I and Receiver II, while skipping Receiver III.

Requirement for creation of sample application

ASP.NET WebHooks provides NuGet packages with which we can easily create our sample application. The following NuGet packages are required to get started with our sample application:

• To start with the sample application, we first need to add support for WebHooks. This would enable the user to register for WebHooks. The Custom NuGet package fulfills this requirement, and is available here.
• The sample application needs to let the users register and provide a facility to subscribe to the events required. The Custom MVC NuGet package fulfills this requirement, and is available here.
• To fulfill Restful API support, we have a Custom API NuGet package, which is available here. 

Apart from these NuGet packages, there is a need to persist and store subscription data. NuGet offers a package to fulfill this requirement with AzureStorage. It can be found here.

SqlStorage is another option for this persistence, and it can be found here.

Starting with the sample application

By now, we have a fundamental grasp of how to create senders and know the basic requirements to create our sample application. Here are a few points that will help us get started with the sample application:

• The sample application will use Azure storage to persist the subscriptions
• Rest API will be available for all subscribers

To get started with sample application, open Solution Explorer in Visual Studio, and then open the WebAPIConfig file. Add the following lines at the end of the Register method.

Code Listing 31

In the preceding code listing, we are initializing support of WebHook in our sample app, and then support for AzureStorage and Apis.

Exposing events for subscription

As we have discussed in the preceding sections, the sender should expose events so that subscribers can subscribe to desired event for notifications. ASP.NET WebHooks provides a facility to declare events with the help of the IWebHookFilterProvider interface. These events are just a class derived from WebHookFilter. Since you can have more than one event, always make the event declaration a collection.

Code Listing 32

In the preceding code listing, we defined three events, representing document creation, updates, and deletion. You can add more events here if you want to expose for subscribers.

Serving notifications

Now we just have to provide a way for our subscribers to get notifications to the subscribed events for the registered WebHook receivers.

Code Listing 33

In Code Listing 30, our API responsible for creation of a new document code is self-explanatory; here we are creating a new document by accepting a document model in the parameter of the Post resource, and immediately after creation of the document, we are notifying with data of a newly created document. This code is not complete, and is only an example to explain sending notifications.

Wrapping up WebHook sender

Earlier, we created a WebHook sender to create notifications for the WebHook receiver; the sample application we discussed is available here.

The next step would be to create a receiver to receive these notifications, which is beyond the scope for this chapter, but would follow the same steps outlined in Chapter 4.

Conclusion

In this chapter we have discussed the creation of a custom sender with a sample application. We looked at the basic framework required to create a sender, and discussed the complexity and scope of sending notifications.