Entrega de eventos de webhook

Artigo
10/18/2023

Webhooks são uma das muitas maneiras de receber eventos da Grade de Eventos do Azure. Quando um novo evento está pronto, o serviço de Grade de Eventos POSTA 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 suportam webhooks, a Grade de Eventos exige que você prove a propriedade do seu ponto de extremidade Webhook antes que ele comece a entregar 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 de grade de eventos

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

Aplicativos Lógicos do Azure com Conector de Grade de Eventos
Automação do Azure via 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 em gatilho HTTP, seu código de ponto de extremidade precisará participar de um handshake de validação com a Grade de Eventos. A Grade de Eventos oferece suporte a duas maneiras de validar a assinatura.

Handshake síncrono: no momento da criação da assinatura do evento, a Grade de Eventos envia um evento de validação de assinatura para seu ponto de extremidade. O esquema deste evento é semelhante a qualquer outro evento da Grade de Eventos. A parte de dados deste evento inclui uma validationCode propriedade. Seu aplicativo verifica se a solicitação de validação é para uma assinatura de evento esperado e retorna o código de validação na resposta de forma síncrona. Este mecanismo de handshake é suportado em todas as versões da Grade de Eventos.
Handshake assíncrono: em certos casos, não é possível retornar a resposta de forma síncrona validationCode . Por exemplo, se você usar um serviço de terceiros (como Zapier ou IFTTT), não poderá responder programaticamente com o código de validação.

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

O URL fornecido é válido por 10 minutos. Durante esse período, o estado de provisionamento 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ê precisa criar a assinatura do evento novamente antes de iniciar a validação manual.

Esse mecanismo de autenticação também requer que o ponto de extremidade webhook retorne um código de status HTTP de 200 para que ele saiba que o POST para o evento de validação foi aceito antes de poder 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 no URL de validação dentro de 10 minutos, o handshake de validação será considerado bem-sucedido.

Nota

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

Detalhes da validação

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

Um exemplo SubscriptionValidationEvent é 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 validationResponse ponto de extremidade, repita o código de validação na propriedade, conforme mostrado no exemplo a seguir:

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

E siga um destes passos:

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

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

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

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

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

Para obter um exemplo de manipulação do handshake de validação de assinatura, consulte um exemplo de C#.

Validação de endpoint com CloudEvents v1.0

O CloudEvents v1.0 implementa sua própria semântica de proteção contra abuso usando o método HTTP OPTIONS . Pode ler mais sobre o assunto aqui. Quando você usa o esquema CloudEvents para saída, a Grade de Eventos usa a proteção contra abuso do CloudEvents v1.0 no lugar do mecanismo de eventos de validação da Grade de Eventos.

Compatibilidade de esquema de eventos

Quando um tópico é criado, um esquema de evento de entrada é 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 eventos de entrada	Esquema de eventos de saída	Suportado
Esquema da Grelha de Eventos	Esquema da Grelha de Eventos	Sim
	Esquema Cloud Events v1.0	Sim
	Esquema de entrada personalizado	Não
Esquema Cloud Events v1.0	Esquema da Grelha de Eventos	Não
	Esquema Cloud Events v1.0	Sim
	Esquema de entrada personalizado	Não
Esquema de entrada personalizado	Esquema da Grelha de Eventos	Sim
	Esquema Cloud Events v1.0	Sim
	Esquema de entrada personalizado	Sim

Próximos passos

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