Receptores de WebHooks do ASP.NETASP.NET WebHooks receivers

Receber WebHooks depende de quem é o remetente.Receiving WebHooks depends on who the sender is. Às vezes, há etapas adicionais, registrando um WebHook verificando que o assinante está realmente escutando.Sometimes there are additional steps registering a WebHook verifying that the subscriber is really listening. Alguns WebHooks fornecem um modelo de push e pull em que a solicitação HTTP POST contém apenas uma referência para as informações de evento que é, em seguida, a serem recuperados de forma independente.Some WebHooks provide a push-to-pull model where the HTTP POST request only contains a reference to the event information which is then to be retrieved independently. Geralmente, o modelo de segurança varia um pouco.Often the security model varies quite a bit.

A finalidade de WebHooks de ASP.NET da Microsoft é torná-la mais simples e mais consistente para conectar sua API sem gastar muito tempo descobrindo como lidar com qualquer variante específico de WebHooks.The purpose of Microsoft ASP.NET WebHooks is to make it both simpler and more consistent to wire up your API without spending a lot of time figuring out how to handle any particular variant of WebHooks.

Um receptor de WebHook é responsável por aceitar e verificar WebHooks de um remetente específico.A WebHook receiver is responsible for accepting and verifying WebHooks from a particular sender. Um receptor de WebHook pode dar suporte a qualquer número de WebHooks, cada um com sua própria configuração.A WebHook receiver can support any number of WebHooks, each with their own configuration. Por exemplo, o receptor de WebHook do GitHub pode aceitar WebHooks de qualquer número de repositórios do GitHub.For example, the GitHub WebHook receiver can accept WebHooks from any number of GitHub repositories.

URIs de receptor de WebHookWebHook Receiver URIs

Instalando o Microsoft ASP.NET WebHooks, você obtém um controlador de WebHook geral que aceita solicitações de WebHook de um número em aberto de serviços.By installing Microsoft ASP.NET WebHooks you get a general WebHook controller which accepts WebHook requests from an open-ended number of services. Quando uma solicitação chega, ele escolhe o receptor apropriado que você instalou para lidar com um remetente de WebHook específico.When a request arrives, it picks the appropriate receiver that you have installed for handling a particular WebHook sender.

O URI deste controlador é o URI do WebHook que você registrar com o serviço e a forma: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}

Por motivos de segurança, muitos receptores de WebHook exigem que o URI é um https URI e em alguns casos, ele também deverá conter um parâmetro de consulta adicionais que é usado para impor que apenas a parte pretendida pode enviar WebHooks para o URI acima .For security reasons, many WebHook receivers require that the URI is an https URI and in some cases it must also contain an additional query parameter which is used to enforce that only the intended party can send WebHooks to the URI above.

O <receiver> componente é o nome do destinatário, por exemplo github ou slack.The <receiver> component is the name of the receiver, for example github or slack.

O {id} é um identificador opcional que pode ser usado para identificar uma determinada configuração de receptor de WebHook.The {id} is an optional identifier which can be used to identify a particular WebHook receiver configuration. Isso pode ser usado para registrar WebHooks N com um receptor em particular.This can be used to register N WebHooks with a particular receiver. Por exemplo, os URIs de três a seguir pode ser usado para se registrar para três WebHooks independentes:For example, the following three URIs can be used to register for three independent WebHooks:

https://<host>/api/webhooks/incoming/github
https://<host>/api/webhooks/incoming/github/12345
https://<host>/api/webhooks/incoming/github/54321

Instalando um receptor de WebHookInstalling a WebHook Receiver

Para receber os WebHooks usando WebHooks do Microsoft ASP.NET, você primeiro instala o pacote do Nuget para o provedor de WebHook ou os provedores que você deseja receber WebHooks de.To receive WebHooks using Microsoft ASP.NET WebHooks, you first install the Nuget package for the WebHook provider or providers you want to receive WebHooks from. Os pacotes do Nuget são nomeados Microsoft.AspNet.WebHooks.Receivers.* onde a última parte indica o serviço de suporte.The Nuget packages are named Microsoft.AspNet.WebHooks.Receivers.* where the last part indicates the service supported. Por exemploFor example

Microsoft.AspNet.WebHooks.Receivers.GitHub fornece suporte para o recebimento de WebHooks do GitHub e Microsoft.AspNet.WebHooks.Receivers.Custom fornece suporte para o recebimento de WebHooks gerado pelo ASP. WebHooks de NET.Microsoft.AspNet.WebHooks.Receivers.GitHub provides support for receiving WebHooks from GitHub and Microsoft.AspNet.WebHooks.Receivers.Custom provides support for receiving WebHooks generated by ASP.NET WebHooks.

Fora da caixa, você pode encontrar suporte para o Dropbox, GitHub, MailChimp, PayPal, Pusher, Salesforce, Slack, distribuição, Trello e WordPress, mas é possível oferecer suporte a qualquer número de outros provedores.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.

Configurando um receptor de WebHookConfiguring a WebHook Receiver

Receptores de WebHook são configurados por meio de IWebHookReceiverConfig interface e implementações específicas dessa interface podem ser registradas usando qualquer modelo de injeção de dependência.WebHook Receivers are configured through the IWebHookReceiverConfig inteface and particular implementations of that interface can be registered using any dependency injection model. A implementação padrão usa as configurações de aplicativo que pode ser definida no arquivo Web. config ou, se usar aplicativos Web do Azure, pode ser definido por meio de Portal do Azure.The default implementation uses Application Settings which can either be set in the Web.config file, or, if using Azure Web Apps, can be set through the Azure Portal.

Configurações de aplicativo do Azure

O formato para as chaves de configuração de aplicativo é da seguinte maneira:The format for Application Setting keys is as follows:

MS_WebHookReceiverSecret_<receiver>

O valor é uma lista separada por vírgulas de valores que corresponde a {id} valores para os quais WebHooks tiver sido registrados, por exemplo:The value is a comma-separated list of values matching the {id} values for which WebHooks have been registered, for example:

MS_WebHookReceiverSecret_GitHub = <secret1>, 12345=<secret2>, 54321=<secret3>

Inicializando um receptor de WebHookInitializing a WebHook Receiver

Receptores de WebHook são inicializados, registrando-os, normalmente na WebApiConfig classe estática, por exemplo: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 routes
            config.MapHttpAttributeRoutes();

            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional }
            );

            // Load receivers
            config.InitializeReceiveGitHubWebHooks();
        }
    }
}