AspNetCore.Docs/webhooks/receiving/handlers.rst

Processing WebHooks
===================

Once WebHooks requests has been validated by a WebHook receiver, it is 
ready to be processed by user code. This is where *handlers* come in. 
Handlers derive from the `IWebHookHandler 
<https://github.com/aspnet/WebHooks/blob/master/src/Microsoft.AspNet.Web 
Hooks.Receivers/WebHooks/WebHookHandler.cs>`_ interface but typically 
uses the `WebHookHandler 
<https://github.com/aspnet/WebHooks/blob/master/src/Microsoft.AspNet.Web 
Hooks.Receivers/WebHooks/WebHookHandler.cs>`_ 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 respective *Order* property going from 
lowest to highest where Order is a simple integer (suggested to be 
between 1 and 100): 

.. image:: _static/Handlers.png
  
A handler can optionally set the *Response* property on the 
WebHookHandlerContext which will lead the processing to stop and the 
response to be sent back as the HTTP response to the WebHook. In the case 
above, Handler C won’t get called 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 the 
originating API. This is for example the case with Slack WebHooks where 
the response is posted back to the channel where the WebHook came from. 
Handlers can set the Receiver property if they only want to receive 
WebHooks from that 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 active and 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 of a handler then that 
handler will only receive WebHook requests from that receiver.

Processing a WebHook
--------------------

When a handler is called, it gets a `WebHookHandlerContext 
<https://github.com/aspnet/WebHooks/blob/master/src/Microsoft.AspNet.Web 
Hooks.Receivers/WebHooks/WebHookHandlerContext.cs>`_ containing 
information about the WebHook request. The data, 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 
`CustomNotifications 
<https://github.com/aspnet/WebHooks/blob/master/src/Microsoft.AspNet.Web 
Hooks.Receivers.Custom/WebHooks/CustomNotifications.cs>`_ as 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);
        }
    }

Queued Processing
-----------------

Most WebHook senders will resend a WebHook if a response is not 
generated within a handful of seconds. This means that 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 
<https://github.com/aspnet/WebHooks/blob/master/src/Microsoft.AspNet.WebHooks.Receivers/WebHooks/WebHookQueueHandler.cs>`_ can be used to submit 
the WebHook request to a queue, for example `Azure Storage Queue <https://msdn.microsoft.com/en-us/library/azure/dd179353.aspx>`_. 

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);
        }
    }