Embed Size (px)
Citation preview
ASP.NET WebHooks DocumentationRelease
Microsoft
Oct 16, 2016
Contents
1 Overview of ASP.NET WebHooks 31.1 WebHooks Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 WebHooks Processing Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2 Source Code and Nugets 72.1 Nuget Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3 Receiving WebHooks 93.1 WebHook Receivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.2 Processing WebHooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113.3 Receiver Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4 Sending WebHooks 154.1 WebHook Senders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5 Diagnostics 175.1 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175.2 Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
6 Contribute 21
i
ii
ASP.NET WebHooks Documentation, Release
Note: This documentation is a work in progress. Topics marked with a are placeholders that have not been writtenyet. You can track the status of these topics through our public documentation issue tracker. Learn how you cancontribute on GitHub.
Contents 1
ASP.NET WebHooks Documentation, Release
2 Contents
CHAPTER 1
Overview of ASP.NET WebHooks
WebHooks is a lightweight HTTP pattern providing a simple pub/sub model for wiring together Web APIs and SaaSservices. When an event happens in a service, a notification is sent in the form of an HTTP POST request to registeredsubscribers. The POST request contains information about the event which makes it possible for the receiver to actaccordingly.
Because of their simplicity, WebHooks are already exposed by a large number of services including Dropbox, GitHub,Bitbucket, MailChimp, PayPal, Slack, Stripe, Trello, and many more. For example, a WebHook can indicate that a filehas changed in Dropbox, or a code change has been committed in GitHub, or a payment has been initiated in PayPal,or a card has been created in Trello. The possibilities are endless!
Microsoft ASP.NET WebHooks makes it easier to both send and receive WebHooks as part of your ASP.NET appli-cation:
• On the receiving side, it provides a common model for receiving and processing WebHooks from any number ofWebHook providers. It comes out of the box with support for Dropbox, GitHub, Bitbucket, MailChimp, PayPal,Pusher, Salesforce, Slack, Stripe, Trello, and WordPress but it is easy to add support for more.
• On the sending side it provides support for managing and storing subscriptions as well as for sending eventnotifications to the right set of subscribers. This allows you to define your own set of events that subscribers cansubscribe to and notify them when things happens.
The two parts can be used together or apart depending on your scenario. If you only need to receive WebHooks fromother services then you can use just the receiver part; if you only want to expose WebHooks for others to consume,then you can do just that.
The code targets ASP.NET Web API 2 and ASP.NET MVC 5 and is available as OSS on GitHub.
1.1 WebHooks Overview
WebHooks is a pattern which means that it varies how it is used from service to service but the basic idea is the same.You can think of WebHooks as a simple pub/sub model where a user can subscribe to events happening elsewhere.The event notifications are propagated as HTTP POST requests containing information about the event itself.
Typically the HTTP POST request contains a JSON object or HTML form data determined by the WebHook senderincluding information about the event causing the WebHook to trigger. For example, an example of a WebHook POSTrequest body from GitHub looks like this as a result of a new issue being opened in a particular repository:
{"action": "opened","issue": {
"url": "https://api.github.com/repos/octocat/Hello-World/issues/1347","number": 1347,
3
ASP.NET WebHooks Documentation, Release
...},"repository": {
"id": 1296269,"full_name": "octocat/Hello-World","owner": {
"login": "octocat","id": 1...
},...
},"sender": {
"login": "octocat","id": 1,...
}}
To ensure that the WebHook is indeed from the intended sender, the POST request is secured in some way and thenverified by the receiver. For example, GitHub WebHooks includes an X-Hub-Signature HTTP header with a hash ofthe request body which is checked by the receiver implementation so you don’t have to worry about it.
The WebHook flow generally goes something like this:
• The WebHook sender exposes events that a client can subscribe to. The events describe observable changes tothe system, for example that a new data item has been inserted, that a process has completed, or something else.
• The WebHook receiver subscribes by registering a WebHook consisting of four things:
1. A URI for where the event notification should be posted in the form of an HTTP POST request;
2. A set of filters describing the particular events for which the WebHook should be fired;
3. A secret key which is used to sign the HTTP POST request;
4. Additional data which is to be included in the HTTP POST request. This can for example be additionalHTTP header fields or properties included in the HTTP POST request body.
• Once an event happens, the matching WebHook registrations are found and HTTP POST requests are submitted.Typically, the generation of the HTTP POST requests are retried several times if for some reason the recipientis not responding or the HTTP POST request results in an error response.
1.2 WebHooks Processing Pipeline
The Microsoft ASP.NET WebHooks processing pipeline for incoming WebHooks looks like this:
4 Chapter 1. Overview of ASP.NET WebHooks
ASP.NET WebHooks Documentation, Release
The two key concepts here are Receivers and Handlers:
• Receivers are responsible for handling the particular flavor of WebHook from a given sender and for enforcingsecurity checks to ensure that the WebHook request indeed is from the intended sender.
• Handlers are typically where user code runs processing the particular WebHook.
In the following nodes these concepts are described in more details.
1.2. WebHooks Processing Pipeline 5
ASP.NET WebHooks Documentation, Release
6 Chapter 1. Overview of ASP.NET WebHooks
CHAPTER 2
Source Code and Nugets
Microsoft ASP.NET WebHooks is part of the Microsoft ASP.NET family of modules and is hosted as an Open SourceProject on GitHub. This means that we accept contributions, but please look at the Contribution Guidelines beforesubmitting a pull request.
This online documentation which you are reading now is also hosted as Open Source on GitHub and also acceptscontributions.
2.1 Nuget Packages
Microsoft ASP.NET WebHooks is also available as preview Nuget packages which means that you have to select thePreview flag in Visual Studio in order to see them.
The Nuget packages are devided into three parts:
• Common: A common package that is shared between senders and receivers.
• Sender: A set of packages supporting sending your own WebHooks to others. The functionality for sendingWebHooks is described in more detail in Sending WebHooks.
• Receivers: A set of packages supporting receiving WebHooks from others. The functionality for receivingWebHooks is described in more detail in Receiving WebHooks.
7
ASP.NET WebHooks Documentation, Release
8 Chapter 2. Source Code and Nugets
CHAPTER 3
Receiving WebHooks
Note: This documentation is a work in progress. Topics marked with a are placeholders that have not been writtenyet. You can track the status of these topics through our public documentation issue tracker. Learn how you cancontribute on GitHub.
3.1 WebHook Receivers
Receiving WebHooks depends on who the sender is. Sometimes there are additional steps registering a WebHookverifying that the subscriber is really listening. Some WebHooks provide a push-to-pull model where the HTTP POSTrequest only contains a reference to the event information which is then to be retrieved independently. Often thesecurity model varies quite a bit.
The purpose of Microsoft ASP.NET WebHooks is to make it both simpler and more consistent to wire up your APIwithout spending a lot of time figuring out how to handle any particular variant of WebHooks.
A WebHook receiver is responsible for accepting and verifying WebHooks from a particular sender. A WebHookreceiver can support any number of WebHooks, each with their own configuration. For example, the GitHub WebHookreceiver can accept WebHooks from any number of GitHub repositories.
3.1.1 WebHook Receiver URIs
By installing Microsoft ASP.NET WebHooks you get a general WebHook controller which accepts WebHook requestsfrom an open-ended number of services. When a request arrives, it picks the appropriate receiver that you haveinstalled for handling a particular WebHook sender.
The URI of this controller is the WebHook URI that you register with the service and is of the form:
https://<host>/api/webhooks/incoming/<receiver>/{id}
For security reasons, many WebHook receivers require that the URI is an https URI and in some cases it must alsocontain an additional query parameter which is used to enforce that only the intended party can send WebHooks to theURI above.
The <receiver> component is the name of the receiver, for example github or slack.
The {id} is an optional identifier which can be used to identify a particular WebHook receiver configuration. Thiscan be used to register N WebHooks with a particular receiver. For example, the following three URIs can be used toregister for three independent WebHooks:
9
ASP.NET WebHooks Documentation, Release
https://<host>/api/webhooks/incoming/githubhttps://<host>/api/webhooks/incoming/github/12345https://<host>/api/webhooks/incoming/github/54321
3.1.2 Installing a WebHook Receiver
To receive WebHooks using Microsoft ASP.NET WebHooks, you first install the Nuget package for the Web-Hook provider or providers you want to receive WebHooks from. The Nuget packages are named Mi-crosoft.AspNet.WebHooks.Receivers.* where the last part indicates the service supported. For example
Microsoft.AspNet.WebHooks.Receivers.GitHub provides support for receiving WebHooks from GitHub and Mi-crosoft.AspNet.WebHooks.Receivers.Custom provides support for receiving WebHooks generated by ASP.NET Web-Hooks.
Out of the box you can find support for Dropbox, GitHub, MailChimp, PayPal, Pusher, Salesforce, Slack, Stripe,Trello, and WordPress but it is possible to support any number of other providers.
3.1.3 Configuring a WebHook Receiver
WebHook Receivers are configured through the IWebHookReceiverConfig inteface and particular implementations ofthat interface can be registered using any dependency injection model. The default implementation uses ApplicationSettings which can either be set in the Web.config file, or, if using Azure Web Apps, can be set through the AzurePortal.
The format for Application Setting keys is as follows:
MS_WebHookReceiverSecret_<receiver>
The value is a comma-separated list of values matching the {id} values for which WebHooks have been registered, forexample:
MS_WebHookReceiverSecret_GitHub = <secret1>, 12345=<secret2>, 54321=<secret3>
10 Chapter 3. Receiving WebHooks
ASP.NET WebHooks Documentation, Release
3.1.4 Initializing a WebHook Receiver
WebHook Receivers are initialized by registering them, typically in the WebApiConfig static class, for example:
namespace WebHookReceivers{
public static class WebApiConfig{
public static void Register(HttpConfiguration config){
// Web API configuration and services
// Web API routesconfig.MapHttpAttributeRoutes();
config.Routes.MapHttpRoute(name: "DefaultApi",routeTemplate: "api/{controller}/{id}",defaults: new { id = RouteParameter.Optional }
);
// Load receiversconfig.InitializeReceiveGitHubWebHooks();
}}
}
3.2 Processing WebHooks
Once WebHooks requests has been validated by a WebHook receiver, it is ready to be processed by user code. This iswhere handlers come in. Handlers derive from the IWebHookHandler interface but typically uses the WebHookHan-dler class instead of deriving directly from the interface.
A WebHook request can be processed by one or more handlers. Handlers are called in order based on their respectiveOrder property going from lowest to highest where Order is a simple integer (suggested to be between 1 and 100):
A handler can optionally set the Response property on the WebHookHandlerContext which will lead the processing tostop and the response to be sent back as the HTTP response to the WebHook. In the case above, Handler C won’t getcalled because it has a higher order than B and B sets the response.
Setting the response is typically only relevant for WebHooks where the response can carry information back to theoriginating API. This is for example the case with Slack WebHooks where the response is posted back to the channel
3.2. Processing WebHooks 11
ASP.NET WebHooks Documentation, Release
where the WebHook came from. Handlers can set the Receiver property if they only want to receive WebHooks fromthat particular receiver. If they don’t set the receiver they are called for all of them.
One other common use of a response is to use a 410 Gone response to indicate that the WebHook no longer is activeand no further requests should be submitted.
By default a handler will be called by all WebHook receivers. However, if the Receiver property is set to the name ofa handler then that handler will only receive WebHook requests from that receiver.
3.2.1 Processing a WebHook
When a handler is called, it gets a WebHookHandlerContext containing information about the WebHook request. Thedata, typically the HTTP request body, is available from the Data property.
The type of the data is typically JSON or HTML form data, but it is possible to cast to a more specific type if desired.For example, the custom WebHooks generated by ASP.NET WebHooks can be cast to the type CustomNotificationsas follows:
public class MyWebHookHandler : WebHookHandler{
public MyWebHookHandler(){
this.Receiver = "custom";}
public override Task ExecuteAsync(string generator, WebHookHandlerContext context){
CustomNotifications notifications = context.GetDataOrDefault<CustomNotifications>();foreach (var notification in notifications.Notifications){
...}return Task.FromResult(true);
}}
3.2.2 Queued Processing
Most WebHook senders will resend a WebHook if a response is not generated within a handful of seconds. This meansthat your handler must complete the processing within that time frame in order not for it to be called again.
If the processing takes longer, or is better handled separately then the WebHookQueueHandler can be used to submitthe WebHook request to a queue, for example Azure Storage Queue.
An outline of a WebHookQueueHandler implementation is provided here:
public class QueueHandler : WebHookQueueHandler{
public override Task EnqueueAsync(WebHookQueueContext context){
// Enqueue WebHookQueueContext to your queuing system of choice
return Task.FromResult(true);}
}
12 Chapter 3. Receiving WebHooks
ASP.NET WebHooks Documentation, Release
3.3 Receiver Dependencies
Microsoft ASP.NET WebHooks is designed with dependency injection in mind. Most dependencies in the system canbe replaced with alternative implementations using a dependency injection engine.
Please see DependencyScopeExtensions for a list of receiver dependencies. If no dependency has been registered, adefault implementation is used. Please see ReceiverServices for a list of default implementations.
3.3. Receiver Dependencies 13
ASP.NET WebHooks Documentation, Release
14 Chapter 3. Receiving WebHooks
CHAPTER 4
Sending WebHooks
Note: This documentation is a work in progress. Topics marked with a are placeholders that have not been writtenyet. You can track the status of these topics through our public documentation issue tracker. Learn how you cancontribute on GitHub.
4.1 WebHook Senders
Please see the blog Sending WebHooks with ASP.NET WebHooks Preview for more details.
15
ASP.NET WebHooks Documentation, Release
16 Chapter 4. Sending WebHooks
CHAPTER 5
Diagnostics
Note: This documentation is a work in progress. Topics marked with a are placeholders that have not been writtenyet. You can track the status of these topics through our public documentation issue tracker. Learn how you cancontribute on GitHub.
5.1 Logging
Microsoft ASP.NET WebHooks uses logging as a way of reporting issues and problems. By default logs are writtenusing System.Diagnostics.Trace where they can be manged using Trace Listeners like any other log stream.
When deploying your Web Application as an Azure Web App, the logs are automatically picked up and can be managedtogether with any other System.Diagnostics.Trace logging. For details, please see Enable diagnostics logging for webapps in Azure App Service
In addition, logs can be obtained straight from inside Visual Studio as described in Troubleshoot a web app in AzureApp Service using Visual Studio.
5.1.1 Redirecting Logs
Instead of writing logs to System.Diagnostics.Trace, it is possible to provide an alternate logging implementationthat can log directly to a log manager such as Log4Net and NLog. Simply provide an implementation of ILoggerand register it with a dependency injection engine of your choice and it will get picked up by Microsoft ASP.NETWebHooks. Please see Dependency Injection in ASP.NET Web API 2 for details.
5.2 Debugging
5.2.1 Debugging in Azure
To debug your Web Application while running in Azure, please see the tutorial Troubleshoot a web app in Azure AppService using Visual Studio.
17
ASP.NET WebHooks Documentation, Release
5.2.2 Debugging with Source and Symbols
In addition to debugging your own code, it is possible to debug directly into Microsoft ASP.NET WebHooks, and infact all of .NET. This works regardless of whether you debug locally or remotely. First, configure Visual Studio to findthe source and symbols by going to Debug and then Options and Settings. Set the options like this:
Then add a link to symbolsource.org for downloading the source and symbols. Go to the Symbols tab of the menuabove and add the following as a symbol location:
http://srv.symbolsource.org/pdb/Public
In addition, make sure that the cache directory has a short name; otherwise the file names can get too long which willcause the symbols to not load. A sample path is:
C:\SymCache
The settings should look similar to this:
18 Chapter 5. Diagnostics
ASP.NET WebHooks Documentation, Release
5.2. Debugging 19
ASP.NET WebHooks Documentation, Release
20 Chapter 5. Diagnostics
CHAPTER 6
Contribute
The documentation on this site is the handiwork of our many contributors.
We accept pull requests! But you’re more likely to have yours accepted if you follow these guidelines:
1. Read https://github.com/aspnet/Docs/blob/master/CONTRIBUTING.md
2. Follow the ASP.NET Docs Style Guide
21
