Entrega de eventos de webhook

  • Artículo

Los webhooks son una de las muchas maneras de recibir eventos de Azure Event Grid. Cuando un nuevo evento está preparado, el servicio EventGrid publica una solicitud HTTP en el punto de conexión configurado con el evento en el cuerpo de la solicitud.

Al igual que muchos otros servicios que admiten webhooks, EventGrid requiere que demuestre la propiedad de su punto de conexión de Webhook antes de que comience a entregar eventos a ese punto de conexión. Este requisito evita que un usuario malintencionado sature el punto de conexión con eventos.

Validación de puntos de conexión con eventos de Event Grid

Cuando se usa cualquiera de los tres servicios de Azure siguientes, la infraestructura de Azure controla automáticamente esta validación:

Si utiliza cualquier otro tipo de punto de conexión, como una función de Azure basada en un desencadenador HTTP, el código del punto de conexión debe participar en un protocolo de enlace de validación con EventGrid. Event Grid admite dos formas de validar la suscripción.

  • Enlace sincrónico: En el momento de crear la suscripción a eventos, Event Grid envía un evento de validación de suscripción en su punto de conexión. El esquema de este evento es similar a cualquier otro evento de Event Grid. La parte de datos de este evento incluye una propiedad validationCode. La aplicación comprueba que la solicitud de validación es para una suscripción a un evento esperado, y devuelve el código de validación en la respuesta de forma sincrónica. Este mecanismo del protocolo de enlace se admite en todas las versiones de EventGrid.

  • protocolo de enlace asíncrono: en ciertos casos, no se puede devolver validationCode en respuesta en forma sincrónica. Por ejemplo, si usa un servicio de terceros (como Zapier o IFTTT), no puede responder con el código de validación mediante programación.

    EventGrid admite un protocolo de enlace de validación manual. Si va a crear una suscripción de eventos mediante el SDK o la herramienta que usa la versión de API 2018-05-01-preview, EventGrid envía una propiedad validationUrl en los datos del evento de validación de suscripción. Para completar el protocolo de enlace, busque esa dirección URL en los datos del evento y envíele una solicitud GET. Puede usar un cliente de REST o el explorador web.

    La dirección URL proporcionada es válida durante 10 minutos. Durante ese tiempo, el estado de aprovisionamiento de la suscripción al eventos es AwaitingManualAction. Si no ha completado la validación manual en 10 minutos, el estado de aprovisionamiento se establece en Failed. Tendrá que crear la suscripción de eventos de nuevo antes de intentar la validación manual.

    Este mecanismo de autenticación también requiere el punto de conexión de webhook para devolver un código de estado HTTP de 200 para que sepa que se aceptó el objeto POST para el evento de validación antes de se pueda colocar en el modo de validación manual. Es decir, si el punto de conexión devuelve 200, pero no devuelve una respuesta de validación de forma sincrónica, el modo se cambia al modo de validación manual. Si hay una operación GET en la dirección URL de validación dentro de un plazo de 10 minutos, se considera que el protocolo de enlace de validación se realizó correctamente.

Nota:

Para la validación no se admite el uso de certificados autofirmados. En su lugar, use un certificado firmado de una entidad de certificación (CA) comercial.

Detalles de la validación

  • En el momento de crear o actualizar la suscripción a eventos, Event Grid publica un evento de validación de suscripción en el punto de conexión de destino.
  • El evento contiene un valor de encabezado aeg-event-type: SubscriptionValidation.
  • El cuerpo del evento tiene el mismo esquema que otros eventos de Event Grid.
  • La propiedad eventType del evento es Microsoft.EventGrid.SubscriptionValidationEvent.
  • La propiedad data del evento incluye una propiedad validationCode con una cadena generada aleatoriamente. Por ejemplo, validationCode: acb13….
  • Los datos del evento también incluyen una propiedad validationUrl con una dirección URL para validar manualmente la suscripción.
  • La matriz contiene solo el evento de validación. Otros eventos se envían en una solicitud aparte después de devolver el código de validación.
  • Los SDK del plano de datos de EventGrid tienen clases que corresponden a los datos de eventos de validación de suscripción y a la respuesta de validación de suscripción.

En el siguiente ejemplo se muestra un evento SubscriptionValidationEvent de ejemplo:

[
  {
    "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 comprobar la propiedad del punto de conexión, devuelva el código de validación en la propiedad validationResponse, como se muestra en el siguiente ejemplo:

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

Y, siga uno de estos pasos:

  • Debe devolver un código de estado de respuesta HTTP 200 OK. HTTP 202 Aceptado no se reconoce como una respuesta válida de validación de suscripción a Event Grid. La solicitud HTTP debe completarse en 30 segundos. Si la operación no finaliza en 30 segundos, se cancelará y puede que se vuelva a intentar pasados cinco segundos. Si se producen errores en todos los intentos, entonces se trata como un error de protocolo de enlace de validación.

    El hecho de que la aplicación esté preparada para controlar y devolver el código de validación indica que ha creado la suscripción de eventos y espera recibir el evento. Imagine el escenario en el que no se admite la validación del protocolo de enlace y que un hacker conoce la dirección URL de la aplicación. El hacker puede crear un tema y una suscripción a eventos con la dirección URL de la aplicación y empezar a realizar un ataque DoS a la aplicación enviando una gran cantidad de eventos. La validación del protocolo de enlace impide que esto suceda.

    Imagine que ya tiene la validación implementada en la aplicación porque ha creado sus propias suscripciones de eventos. Incluso si un hacker crea una suscripción de eventos con la dirección URL de la aplicación, la implementación correcta del evento de solicitud de validación comprobará el encabezado aeg-subscription-name de la solicitud para comprobar que es una suscripción de eventos que reconoce.

    Incluso después de esa implementación correcta del protocolo de enlace, un hacker puede inundar la aplicación (ya validó la suscripción de eventos) mediante la replicación de una solicitud que parece provenida de Event Grid. Para evitarlo, debe proteger el webhook con la autenticación de Microsoft Entra. Para obtener más información, consulte Entrega de eventos a puntos de conexión protegidosde Microsoft Entra.

  • O bien, puede enviar una solicitud GET a la dirección URL de validación para validar la suscripción manualmente. La suscripción a eventos permanece en estado pendiente hasta que se valida. La dirección URL de validación usa el puerto 553. Si las reglas de tu firewall bloquean el puerto 553, necesitarás actualizar las reglas para que el protocolo de enlace manual sea exitoso.

    En la validación del evento de validación de la suscripción, si identifica que no es una suscripción de eventos para la que espera eventos, no devolverá una respuesta 200 o ninguna respuesta en absoluto. Por lo tanto, se produce un error en la validación.

Para ver un ejemplo del tratamiento del protocolo de enlace de validación de suscripción, consulte un ejemplo de C#.

Validación de puntos de conexión con CloudEvents v1.0

CloudEvents v1.0 implementa su propia semántica de protección contra abusos mediante el método HTTP OPTIONS. Puede leer más sobre este tema aquí. Cuando usa el esquema de CloudEvents para la salida, Event Grid usa la protección contra abusos de CloudEvents v1.0 en lugar del mecanismo de eventos de validación de Event Grid.

Compatibilidad del esquema de eventos

Cuando se crea un tema, se define un esquema de eventos entrantes. Y, cuando se crea una suscripción, se define un esquema de eventos salientes. En la tabla siguiente se muestra la compatibilidad permitida al crear una suscripción.

Esquema de eventos entrantes Esquema de eventos salientes Compatible
Esquema de Event Grid Esquema de Event Grid Sí
Esquema de eventos en la nube v1.0 Sí
Esquema de entrada personalizado No
Esquema de eventos en la nube v1.0 Esquema de Event Grid No
Esquema de eventos en la nube v1.0 Sí
Esquema de entrada personalizado No
Esquema de entrada personalizado Esquema de Event Grid Sí
Esquema de eventos en la nube v1.0 Sí
Esquema de entrada personalizado Sí

Pasos siguientes

Consulte el siguiente artículo para obtener información sobre cómo solucionar problemas de validaciones de suscripciones de eventos: Solución de problemas de validacionesde suscripciones de eventos.