Introducing ASP.NET WebHooks Receivers - WebHooks made easy.

There's been a lot of enthusiasm lately about the direction that ASP.NET is going lately, and rightfully so.

• Support for running ASP.NET on Mac, Linux, and Windows, all happening on GitHub at http://github.com/aspnet/home
• Our weekly community standup where you talk to us, every week at http://live.asp.net
• Open Source Documentation supported by ReadTheDocs and up at http://docs.asp.net

However, while ASP.NET 5 is cool and exciting, it's also not yet released (at the time of this writing, Beta 8 is being worked on). There are very cool things happening around ASP.NET 4.6 which is released and ready to go live today. Something else that's VERY cool that I want to explore today is ASP.NET WebHooks, which just came out as a preview and is being actively worked on.

Just as there's Web Forms, MVC, SignalR, Web API and they are all components within ASP.NET, you can think of Web Hooks as another member of the ASP.NET family of technologies. When you want it, it's there to plug in. If you don't use it, it costs you nothing in weight or runtime.

What are WebHooks?

Let's start with the What Are They part of the conversation. WebHooks are a convention. They are HTTP callbacks. Moreover, they are "user-defined HTTP callbacks." You and/or your app signs up for notification when something happens and your URL endpoint will get an HTPT POST when that thing happens. WebHooks can and should be RESTful as well. That means if you have a nice RESTful Web API then adding WebHooks to your application should not only be easy, it should a natural and clean extension.

So what? Why do we need a library for this?

Technically you don't, of course. You could theoretically implement the WebHooks pattern with an HttpHandler if you felt you had something to prove. You could more reasonably do it with ASP.NET Web API, but the general thinking is that if there's a clear and common pattern for doing something then it should be made easier and codified for correctness.

Even more, since WebHooks is such a common pattern and it's being used by folks like Dropbox, GitHub,MailChimp, PayPal, Pusher, Salesforce, Slack, Stripe, Trello, and WordPress then it'd be nice if ASP.NET came with support for these right out of the box. And it does. Support for receiving all of these and more is included.

There is also a need for easy ways for your applications to send events as WebHooks. In order to do that you need to manage and store subscriptions, and when the time comes to correctly make the callbacks to the right set of subscribers.

ASP.NET WebHooks

ASP.NET WebHooks is open source, being actively developed on GitHub and is targeting ASP.NET Web API 2 and ASP.NET MVC 5 today. It helps deal with the administrivia involved in dealing with WebHooks. It was announced on the Microsoft WebDev blog (you should subscribe) a few weeks back.

There's some great docs already being written but the most interesting bits are in the many examples.

• Integrating with Slack Using ASP.NET WebHooks Preview
• Integrating with Salesforce using ASP.NET WebHooks Preview
• Integrating with Instagram using ASP.NET WebHooks Preview
• Sending WebHooks with ASP.NET WebHooks Preview

When you install ASP.NET WebHooks you get a WebHook Handler that is the receiver to accept WebHook requests from services. Using a GitHub WebHook as an example, you can easily make a new project then publish it to Azure WebSites. GitHub WebHooks are required to use SSL for their transport which could be a barrier, but Azure WebSites using the *.azurewebsites.net domain get SSL for free. This will make your first WebHook and testing easier.

A good starter WebHook to try creating is one that gets called when an event happens on GitHub. For example, you might want a notification when someone comments on a GitHub issue as a first step in creating a GitHub bot.

The default routing structure is https://<host>/api/webhooks/incoming/<receiver> which you'll put in your GitHub repository's settings, along with a SHA256 hash or some other big secret. The secret is then put in a config setting called MS_WebHookReceiverSecret_GitHub in this example.

public class GitHubHandler : WebHookHandler

{

    public override Task ExecuteAsync(string receiver, WebHookHandlerContext context)

    {

        string action = context.Actions.First();

        JObject data = context.GetDataOrDefault<JObject>();

 

        return Task.FromResult(true);

    }

}

In this tiny example, the "action" string will contain "issues" if someone comments on an issue (meaning it's an event coming from the "issues" source).

Once you've been triggered by a WebHook callback, you can decide what to do about it. You might want to simply respond, log something, or start a more sophisticated process. There's even a way to trigger an Azure WebJob with this new extension.

More WebHooks

Sending WebHooks is similarly simple and there's already a great post on how to get started here. Finally there's even some skunkworks tooling by Brady Gaster that plugs into Visual Studio 2015 and makes things even easier.

Go check out ASP.NET Web Hooks and give your feedback in the GitHub issues or directly to Henrik or Brady on Twitter!

Sponsor: Thanks to my friends and Infragistics for sponsoring the feed this week. Responsive web design on any browser, any platform and any device with Infragistics jQuery/HTML5 Controls.  Get super-charged performance with the world’s fastest HTML5 Grid - Download for free now!