Visão geral de ASP.NET WebHooks

WebHooks é um padrão HTTP leve que fornece um modelo simples pub/sub para ligar APIs Web e serviços SaaS. Quando ocorre um evento num serviço, é enviada uma notificação sob a forma de um pedido HTTP POST aos assinantes registados. O pedido POST contém informações sobre o evento que permitem ao destinatário agir em conformidade.

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

O Microsoft ASP.NET WebHooks facilita tanto o envio como a receção de WebHooks como parte da sua aplicação ASP.NET:

• No lado recetor, fornece um modelo comum para receber e processar WebHooks de qualquer número de provedores de WebHooks. Vem de fábrica com suporte para Dropbox, GitHub, Bitbucket, MailChimp, PayPal, Pusher, Salesforce, Slack, Stripe, Trello, WordPress e Zendesk mas é fácil adicionar suporte para mais.

• No lado do envio, oferece suporte para gerir e armazenar subscrições, bem como para enviar notificações de eventos ao grupo certo de subscritores. Isto permite-lhe definir o seu próprio conjunto de eventos aos quais os subscritores podem subscrever-se e notificá-los quando algo acontecer.

As duas partes podem ser usadas juntas ou separadas, dependendo do seu cenário. Se só precisar de receber WebHooks de outros serviços, pode usar apenas a parte do recetor; Se só queres expor WebHooks para outros consumirem, então podes fazer exatamente isso.

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

Visão Geral do WebHooks

WebHooks é um padrão, o que significa que varia a forma como é usado de serviço para serviço, mas a ideia básica é a mesma. Pode pensar nos WebHooks como um modelo simples de pub/sub onde um utilizador pode subscrever eventos que acontecem noutros locais. As notificações de eventos são propagadas como pedidos HTTP POST contendo informações sobre o próprio evento.

Normalmente, o pedido 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 causa o disparo do WebHook. Por exemplo, um corpo de pedido POST WebHook de GitHub apresenta-se assim devido à abertura de um novo problema num determinado repositório:

{
  "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 é realmente do remetente pretendido, o pedido POST é protegido de alguma forma e depois verificado pelo destinatário. Por exemplo, GitHub WebHooks inclui um cabeçalho HTTP X-Hub-Signature com um hash do corpo do pedido que é verificado pela implementação do recetor, por isso não tem de se preocupar com isso.

O fluxo do WebHook geralmente funciona mais ou menos assim:

• O remetente do WebHook expõe eventos aos quais um cliente pode subscrever. Os eventos descrevem alterações observáveis ao sistema, por exemplo, que um novo elemento de dados foi inserido, que um processo foi concluído, ou outra coisa qualquer.

• O recetor WebHook subscreve registando um WebHook composto por quatro coisas:

  1. Um URI para onde a notificação do evento deve ser publicada sob a forma de um pedido HTTP POST;

  2. Um conjunto de filtros que descrevem os eventos particulares para os quais o WebHook deve ser disparado;

  3. Uma chave secreta usada para assinar o pedido HTTP POST;

  4. Dados adicionais que devem ser incluídos no pedido HTTP POST. Isto pode, por exemplo, incluir campos adicionais de cabeçalho HTTP ou propriedades incluídas no corpo do pedido HTTP POST.

• Uma vez que ocorre um evento, os registos correspondentes do WebHook são encontrados e os pedidos HTTP POST são submetidos. Normalmente, a geração dos pedidos HTTP POST é retentada várias vezes se, por algum motivo, o destinatário não estiver a responder ou se o pedido HTTP POST resultar numa resposta de erro.

Pipeline de Processamento WebHooks

O pipeline de processamento Microsoft ASP.NET WebHooks para WebHooks recebidos é o seguinte:

Os dois conceitos-chave aqui são Recetores e Manipuladores:

• Os recetores são responsáveis por gerir a versão específica do WebHook de um determinado remetente e por aplicar verificações de segurança para garantir que o pedido WebHook é realmente do remetente pretendido.

• Normalmente, os handlers são onde o código do utilizador é executado ao processar o WebHook em questão.

Nos nós seguintes, estes conceitos são descritos com mais detalhe.