Visão geral do ASP.NET WebHooks

Aviso

ASP.NET WebHooks foi preterido e não receberá mais atualizações ou correções de segurança.

WebHooks é um padrão HTTP simples e leve que fornece um modelo simples de pub/sub para conectar APIs web e Serviços SaaS. Quando um evento acontece em um serviço, uma notificação é enviada na forma de uma solicitação HTTP POST para assinantes registrados. O pedido POST contém informações sobre o evento que permitem que o recetor atue em conformidade.

Devido à simplicidade, os WebHooks já são expostos por um grande número de serviços, incluindo Dropbox, GitHubBitbucket, MailChimp, PayPal, Slack, Stripe, Trello e muito mais. Por exemplo, um WebHook pode indicar que um arquivo foi alterado em Dropbox, ou uma alteração de código foi confirmada em GitHub ou um pagamento foi iniciado em PayPal ou um cartão foi criado em Trello. As possibilidades são infinitas!

O Microsoft ASP.NET WebHooks facilita o envio e o recebimento de WebHooks como parte do aplicativo ASP.NET:

• No lado receptor, ele fornece um modelo comum para receber e processar WebHooks de qualquer número de provedores de WebHook. Ele sai da caixa com suporte para Dropbox, GitHub, BitbucketMailChimp, PayPal, Pusher, Salesforce, Slack, Stripe, Trello,WordPress e Zendesk mas é fácil adicionar suporte para mais.

• No lado do envio, ele fornece suporte para gerenciamento e armazenamento de assinaturas, bem como para enviar notificações de evento para o conjunto certo de assinantes. Isso permite que você defina seu próprio conjunto de eventos que os assinantes podem assinar e notificá-los quando as coisas acontecem.

As duas partes podem ser usadas juntas ou separadas dependendo do seu cenário. Se você só precisar receber WebHooks de outros serviços, poderá usar apenas a parte receptora; se você quiser apenas expor WebHooks para outras pessoas consumirem, você poderá fazer exatamente isso.

O código é direcionado a ASP.NET Web API 2 e ASP.NET MVC 5 e está disponível como OSS no GitHub.

Visão geral dos WebHooks

WebHooks é um padrão que significa que ele varia como ele é usado de serviço para serviço, mas a ideia básica é a mesma. Você pode pensar em WebHooks como um modelo simples de pub/sub, em que um usuário pode assinar eventos que ocorrem em outro lugar. As notificações de evento são propagadas como solicitações HTTP POST contendo informações sobre o evento em si.

Normalmente, a solicitação HTTP POST contém um objeto JSON ou dados de formulário HTML determinados pelo remetente do WebHook, incluindo informações sobre o evento que faz com que o WebHook seja disparado. Por exemplo, um corpo de solicitação POST do WebHook de GitHub tem esta aparência como resultado de um novo problema sendo aberto em um repositório específico:

{
  "action": "opened",
  "issue": {
      "url": "https://api.github.com/repos/octocat/Hello-World/issues/1347",
      "number": 1347,
      ...
  },
  "repository": {
      "id": 1296269,
      "full_name": "octocat/Hello-World",
      "owner": {
          "login": "octocat",
          "id": 1
          ...
      },
      ...
  },
  "sender": {
      "login": "octocat",
      "id": 1,
      ...
  }
}

Para garantir que o WebHook seja de fato do remetente pretendido, a solicitação POST é protegida de alguma forma e verificada pelo receptor. Por exemplo, GitHub WebHooks inclui um cabeçalho HTTP X-Hub-Signature com um hash do corpo da solicitação que é verificado pela implementação do receptor para que você não precise se preocupar com isso.

O fluxo do WebHook geralmente é semelhante a este:

• O remetente do WebHook expõe eventos aos quais um cliente pode assinar. Os eventos descrevem alterações observáveis no sistema, por exemplo, que um novo item de dados foi inserido, que um processo foi concluído ou algo mais.

• O receptor do WebHook assina registrando um WebHook que consiste em quatro coisas:

  1. Um URI para onde a notificação de evento deve ser postada na forma de uma solicitação HTTP POST;

  2. Um conjunto de filtros que descrevem os eventos específicos para os quais o WebHook deve ser acionado;

  3. Uma chave secreta que é usada para assinar a solicitação HTTP POST;

  4. Dados adicionais que devem ser incluídos na solicitação HTTP POST. Isso pode, por exemplo, ser campos de cabeçalho HTTP adicionais ou propriedades incluídas no corpo da solicitação HTTP POST.

• Depois que um evento acontece, os registros de WebHook correspondentes são encontrados e as solicitações HTTP POST são enviadas. Normalmente, a geração das solicitações HTTP POST é repetida várias vezes se, por algum motivo, o destinatário não estiver respondendo ou a solicitação HTTP POST resultar em uma resposta de erro.

Pipeline de Processamento de WebHooks

O pipeline de processamento dos WebHooks de entrada no Microsoft ASP.NET WebHooks se apresenta da seguinte forma:

Os dois principais conceitos aqui são Receptores e Manipuladores:

• Os receptores são responsáveis por lidar com a variante específica do WebHook de um determinado remetente e pela realização de verificações de segurança para garantir que a solicitação do WebHook seja, de fato, do remetente pretendido.

• Normalmente, os manipuladores são onde o código do usuário realiza o processamento de um WebHook específico.

Nos nós seguintes, esses conceitos são descritos em mais detalhes.