Entrega de eventos do webhook

Artigo
09/25/2023

Webhooks são uma dentre várias maneiras de receber eventos da Grade de Eventos do Azure. Quando um novo evento está pronto, o serviço Grade de Eventos faz o POST de uma solicitação HTTP para o ponto de extremidade configurado com as informações do evento no corpo da solicitação.

Como muitos outros serviços que dão suporte a webhooks, a Grade de Eventos do Azure exige que você comprovar a "propriedade" de seu ponto de extremidade do Webhook antes de começar a entrega de eventos para esse ponto de extremidade. Esse requisito impede que um usuário mal-intencionado inunde seu ponto de extremidade com eventos.

Validação de ponto de extremidade com eventos da Grade de Eventos

Quando você usa qualquer um dos seguintes três serviços do Azure, a infraestrutura do Azure trata automaticamente essa validação:

Aplicativos Lógicos do Azure com Conector da Grade de Eventos
Automação do Azure por meio de webhook
Azure Functions com Gatilho de Grade de Eventos

Se você estiver usando qualquer outro tipo de ponto de extremidade, como uma função do Azure baseada no gatilho HTTP, o código do ponto de extremidade precisará participar de um handshake de validação com o EventGrid. A Grade de Eventos dá suporte a duas maneiras de validar a assinatura.

Handshake síncrono: No momento da criação da assinatura, a Grade de Eventos posta um Evento de Validação de Assinatura para o ponto de extremidade de destino. O esquema desse evento é semelhante a qualquer outro evento da Grade de Eventos. A parte de dados desse evento inclui um validationCode propriedade. Seu aplicativo verifica se a solicitação de validação é para uma assinatura de evento esperada e retorna o código de validação na resposta de forma síncrona. Esse mecanismo de handshake é compatível com todas as versões da Grade de Eventos.
Handshake assíncrono: em determinados casos, você não pode retornar o validationCode em resposta de forma síncrona. Por exemplo, se você usar um serviço de terceiros (como Zapier ou IFTTT), não será possível responder de volta programaticamente com o código de validação.

A Grade de Eventos dá suporte a um handshake de validação manual. Se você estiver criando uma inscrição de evento com um SDK ou ferramenta que usa a versão da API 2018-05-01-preview ou posterior, a Grade de Eventos envia uma propriedade validationUrl na parte de dados do evento de validação da assinatura. Para concluir o handshake, localize essa URL nos dados do evento e faça uma solicitação GET para ele. Você pode usar um cliente REST ou o navegador da web.

A URL fornecida é válida por 10 minutos. Durante esse tempo, o estado de fornecimento da assinatura do evento é AwaitingManualAction. Se você não concluir a validação manual em 10 minutos, o estado de provisionamento será definido como Failed. Você terá que criar a assinatura do evento novamente antes de iniciar a validação manual.

Esse mecanismo de autenticação também exige que o ponto de extremidade do webhook retorne um código de status HTTP 200 para que ele saiba que o POST do evento de validação foi aceito antes que ele possa ser colocado no modo de validação manual. Em outras palavras, se o ponto de extremidade retornar 200, mas não retornar uma resposta de validação de forma síncrona, o modo será transferido para o modo de validação manual. Se houver um GET na URL de validação dentro de 10 minutos, o handshake de validação será considerado bem-sucedido.

Observação

Não há suporte para o uso de certificados autoassinados para validação. Em vez disso, use um certificado assinado de uma AC (autoridade de certificação) comercial.

Detalhes da validação

No momento da criação/atualização da assinatura, a Grade de Eventos posta um Evento de Validação de Assinatura para o ponto de extremidade de destino.
O evento contém um valor de cabeçalho aeg-event-type: SubscriptionValidation.
O corpo do evento tem o mesmo esquema que outros eventos da Grade de Eventos.
A propriedade eventType do evento é Microsoft.EventGrid.SubscriptionValidationEvent.
A propriedade validationCode do evento inclui uma propriedade data com uma cadeia de caracteres gerada aleatoriamente. Por exemplo, validationCode: acb13….
Os dados do evento também incluem uma propriedade validationUrl com uma URL para validar manualmente a assinatura.
A matriz contém apenas o evento de validação. Outros eventos serão enviados em uma solicitação separada, após retornar o código de validação.
Os SDKs do plano de dados EventGrid têm classes correspondentes para os dados de evento de validação de assinatura e a resposta de validação de assinatura.

Um SubscriptionValidationEvent de exemplo é mostrado no exemplo a seguir:

[
  {
    "id": "2d1781af-3a4c-4d7c-bd0c-e34b19da4e66",
    "topic": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "subject": "",
    "data": {
      "validationCode": "512d38b6-c7b8-40c8-89fe-f46f9e9622b6",
      "validationUrl": "https://rp-eastus2.eventgrid.azure.net:553/eventsubscriptions/myeventsub/validate?id=0000000000-0000-0000-0000-00000000000000&t=2022-10-28T04:23:35.1981776Z&apiVersion=2018-05-01-preview&token=1A1A1A1A"
    },
    "eventType": "Microsoft.EventGrid.SubscriptionValidationEvent",
    "eventTime": "2022-10-28T04:23:35.1981776Z",
    "metadataVersion": "1",
    "dataVersion": "1"
  }
]

Para provar a propriedade do ponto de extremidade, retorne o código de validação na propriedade validationResponse, conforme mostrado no seguinte exemplo:

{
  "validationResponse": "512d38b6-c7b8-40c8-89fe-f46f9e9622b6"
}

E siga uma destas etapas:

Você deve retornar um código de status de resposta HTTP 200 OK. HTTP 202 Accepted não é reconhecido como uma resposta de validação de assinatura de Grade de Eventos válida. A solicitação HTTP deve ser concluída dentro de 30 segundos. Se a operação não for concluída dentro de 30 segundos, a operação será cancelada e poderá ser tentada novamente após cinco segundos. Se todas as tentativas falharem, elas serão tratadas como um erro de handshake de validação.

O fato de o aplicativo estar preparado para manipular e retornar o código de validação indica que você criou a assinatura do evento e deve receber o evento. Imagine o cenário em que não há suporte para validação de handshake e um hacker consegue saber a URL do aplicativo. O hacker pode criar um tópico e uma assinatura do evento com a URL do aplicativo e começar a realizar um ataque de DoS ao aplicativo enviando muitos eventos. A validação do handshake impede que isso aconteça.

Imagine que você já tenha a validação implementada no aplicativo, pois criou suas próprias assinaturas do evento. Mesmo que um hacker crie uma assinatura do evento com a URL do aplicativo, a implementação correta do evento de solicitação de validação verificará o cabeçalho aeg-subscription-name na solicitação, para confirmar se é uma assinatura do evento que você reconhece.

Mesmo após a implementação correta do handshake, um hacker pode inundar o aplicativo (ele já validou a assinatura do evento) replicando uma solicitação que parece ser proveniente da Grade de Eventos. Para evitar isso, você deve proteger o webhook com a autenticação do Microsoft Entra. Para obter mais informações, confira Entregar eventos aos pontos de extremidade protegidos do Microsoft Entra.
Ou então, você pode validar a assinatura manualmente, enviando uma solicitação GET para a URL de validação. A inscrição do evento permanece em um estado pendente até que validada. A URL de validação usa a porta 553. Se as regras de firewall bloquearem a porta 553, será necessário atualizar as regras para obter um handshake manual bem-sucedido.

Na validação do evento de validação da assinatura, se você identificar que não é uma assinatura do evento para a qual você está esperando eventos, você não retornará uma resposta 200 ou nenhuma resposta. Portanto, a validação falhará.

Para obter um exemplo de lidar com o handshake de validação de assinatura, consulte uma amostra C#.

Validação de ponto de extremidade com CloudEvents v 1.0

CloudEvents v1.0 implementa sua própria semântica de proteção contra abusos usando o método HTTP OPTIONS. Saiba mais sobre isso aqui. Ao usar o esquema CloudEvents para saída, a Grade de Eventos usa com a proteção de abuso do CloudEvents v1.0 em vez do mecanismo de evento de validação da Grade de Eventos.

Compatibilidade do esquema de evento

Quando um tópico é criado, um esquema de eventos recebidos é definido. E, quando uma assinatura é criada, um esquema de evento de saída é definido. A tabela a seguir mostra a compatibilidade permitida ao criar uma assinatura.

Esquema de evento de entrada	Esquema de evento de saída	Com suporte
Esquema da Grade de Eventos	Esquema da Grade de Eventos	Sim
	Esquema de Eventos de Nuvem v1.0	Sim
	Esquema de entrada personalizado	Não
Esquema de Eventos de Nuvem v1.0	Esquema da Grade de Eventos	Não
	Esquema de Eventos de Nuvem v1.0	Sim
	Esquema de entrada personalizado	Não
Esquema de entrada personalizado	Esquema da Grade de Eventos	Sim
	Esquema de Eventos de Nuvem v1.0	Sim
	Esquema de entrada personalizado	Sim

Próximas etapas

Consulte o seguinte artigo para saber como solucionar problemas de validações de assinatura de evento: Solucionar problemas de validações de assinatura de evento.

Share via