|
3 | 3 | Processing WebHooks |
4 | 4 | =================== |
5 | 5 |
|
| 6 | +Once WebHooks requests has been validate by a WebHook receiver, it is |
| 7 | +ready to be processed by user code. This is where *handlers* come in. |
| 8 | +Handlers derive from the `IWebHookHandler |
| 9 | +<https://github.com/aspnet/WebHooks/blob/master/src/Microsoft.AspNet.Web |
| 10 | +Hooks.Receivers/WebHooks/WebHookHandler.cs>`_ interface but typically |
| 11 | +uses the `WebHookHandler |
| 12 | +<https://github.com/aspnet/WebHooks/blob/master/src/Microsoft.AspNet.Web |
| 13 | +Hooks.Receivers/WebHooks/WebHookHandler.cs>`_ class instead of deriving |
| 14 | +directly from the interface. |
6 | 15 |
|
| 16 | +A WebHook request can be processed by one or more handlers. Handlers are |
| 17 | +called in order based on their respective *Order* property going from |
| 18 | +lowest to highest where Order is a simple integer (suggested to be |
| 19 | +between 1 and 100): |
7 | 20 |
|
| 21 | +.. image:: _static/Handlers.png |
| 22 | + |
| 23 | +A handler can optionally set the *Response* property on the |
| 24 | +WebHookHandlerContext which will lead the processing to stop and the |
| 25 | +response to be sent back as the HTTP response to the WebHook. In the case |
| 26 | +above, Handler C won’t get called because it has a higher order than B |
| 27 | +and B sets the response. |
8 | 28 |
|
9 | | -.. include:: /../common/stub-notice.txt |
| 29 | +Setting the response is typically only relevant for |
| 30 | +WebHooks where the response can carry information back to the |
| 31 | +originating API. This is for example the case with Slack WebHooks where |
| 32 | +the response is posted back to the channel where the WebHook came from. |
| 33 | +Handlers can set the Receiver property if they only want to receive |
| 34 | +WebHooks from that particular receiver. If they don’t set the receiver |
| 35 | +they are called for all of them. |
10 | 36 |
|
11 | | -.. _issue: https://github.com/aspnet/Docs/issues/111 |
| 37 | +One other common use of a response is to use a *410 Gone* response to |
| 38 | +indicate that the WebHook no longer is active and no further requests |
| 39 | +should be submitted. |
| 40 | + |
| 41 | +By default a handler will be called by all WebHook receivers. However, |
| 42 | +if the *Receiver* property is set to the name of a handler then that |
| 43 | +handler will only receive WebHook requests from that receiver. |
| 44 | + |
| 45 | +Processing a WebHook |
| 46 | +-------------------- |
| 47 | + |
| 48 | +When a handler is called, it gets a `WebHookHandlerContext |
| 49 | +<https://github.com/aspnet/WebHooks/blob/master/src/Microsoft.AspNet.Web |
| 50 | +Hooks.Receivers/WebHooks/WebHookHandlerContext.cs>`_ containing |
| 51 | +information about the WebHook request. The data, typically the HTTP |
| 52 | +request body, is available from the *Data* property. |
| 53 | + |
| 54 | +The type of the data is typically JSON or HTML form data, but it is |
| 55 | +possible to cast to a more specific type if desired. For example, the |
| 56 | +custom WebHooks generated by ASP.NET WebHooks can be cast to the type |
| 57 | +`CustomNotifications |
| 58 | +<https://github.com/aspnet/WebHooks/blob/master/src/Microsoft.AspNet.Web |
| 59 | +Hooks.Receivers.Custom/WebHooks/CustomNotifications.cs>`_ as follows:: |
| 60 | + |
| 61 | + public class MyWebHookHandler : WebHookHandler |
| 62 | + { |
| 63 | + public CustomWebHookHandler() |
| 64 | + { |
| 65 | + this.Receiver = "custom"; |
| 66 | + } |
| 67 | + |
| 68 | + public override Task ExecuteAsync(string generator, WebHookHandlerContext context) |
| 69 | + { |
| 70 | + CustomNotifications notifications = context.GetDataOrDefault<CustomNotifications>(); |
| 71 | + foreach (var notification in notifications.Notifications) |
| 72 | + { |
| 73 | + ... |
| 74 | + } |
| 75 | + return Task.FromResult(true); |
| 76 | + } |
| 77 | + } |
| 78 | + |
| 79 | +Queued Processing |
| 80 | +----------------- |
| 81 | + |
| 82 | +Most WebHook senders will resend a WebHook if a response is not |
| 83 | +generated within a handful of seconds. This means that your handler must |
| 84 | +complete the processing within that timeframe in order not for it to be |
| 85 | +called again. |
| 86 | + |
| 87 | +If the processing takes longer, or is better handled separately then the |
| 88 | +`WebHookQueueHandler |
| 89 | +<https://github.com/aspnet/WebHooks/blob/master/src/Microsoft.AspNet.WebHooks.Receivers/WebHooks/WebHookQueueHandler.cs>`_ can be used to submit |
| 90 | +the WebHook request to a queue, for example `Azure Storage Queue <https://msdn.microsoft.com/en-us/library/azure/dd179353.aspx>`_. |
| 91 | + |
| 92 | +An outline of a WebHookQueueHandler_ implementation is provided here:: |
| 93 | + |
| 94 | + public class QueueHandler : WebHookQueueHandler |
| 95 | + { |
| 96 | + public override Task EnqueueAsync(WebHookQueueContext context) |
| 97 | + { |
| 98 | + |
| 99 | + // Enqueue WebHookQueueContext to your queueing system of choice |
| 100 | + |
| 101 | + return Task.FromResult(true); |
| 102 | + } |
| 103 | + } |
0 commit comments