Información general de WebHooks de ASP.NET

WebHooks es un patrón HTTP ligero que proporciona un modelo sencillo de publicación y envío para conectar API web y servicios SaaS. Cuando se produce un evento en un servicio, se envía una notificación en forma de una solicitud HTTP POST a los suscriptores registrados. La solicitud POST contiene información sobre el evento que permite al receptor actuar en consecuencia.

Debido a su simplicidad, los WebHooks ya están expuestos por un gran número de servicios, como Dropbox, GitHub, Bitbucket, MailChimp, PayPal, Slack, Stripe, Trello y muchos más. Por ejemplo, un WebHook puede indicar que un archivo ha cambiado en Dropbox o que se ha confirmado un cambio de código en GitHub o que se ha iniciado un pago en PayPal o que se ha creado una tarjeta en Trello. ¡Las posibilidades son infinitas!

Los WebHooks de Microsoft ASP.NET facilitan tanto el envío como la recepción de WebHooks como parte de la aplicación de ASP.NET:

  • En el lado receptor, proporciona un modelo común para recibir y procesar WebHooks de cualquier número de proveedores de WebHook. Viene de fábrica con compatibilidad con Dropbox, GitHub, Bitbucket, MailChimp, PayPal, Pusher, Salesforce, Slack, Stripe, Trello,WordPress y Zendesk, pero es fácil agregar compatibilidad para más.

  • En el lado de envío, proporciona compatibilidad para administrar y almacenar suscripciones, así como para enviar notificaciones de eventos al conjunto adecuado de suscriptores. Esto le permite definir su propio conjunto de eventos a los que los suscriptores pueden suscribirse y notificarlos cuando suceden cosas.

Las dos partes se pueden usar juntas o separadas en función de su escenario. Si solo necesita recibir WebHooks de otros servicios, puede usar solo la parte receptora; si solo desea exponer WebHooks para que otros consuman, puede hacerlo.

El código tiene como destino ASP.NET Web API 2 y ASP.NET MVC 5 y está disponible como OSS en GitHub.

Información general sobre WebHooks

Los WebHooks son un patrón, lo que significa que varía la forma en que se usa del servicio al servicio, pero la idea básica es la misma. Puede pensar en WebHooks como un simple modelo pub/sub donde un usuario puede suscribirse a eventos que se producen en otro lugar. Las notificaciones de eventos se propagan como solicitudes HTTP POST que contienen información sobre el propio evento.

Normalmente, la solicitud HTTP POST contiene un objeto JSON o datos de formulario HTML determinados por el remitente de WebHook, incluida la información sobre el evento que provoca que el WebHook se desencadene. Por ejemplo, un cuerpo de solicitud POST de WebHook de GitHub tiene este aspecto como resultado de un nuevo problema que se abre en un repositorio determinado:

{
  "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 asegurarse de que el WebHook procede del remitente previsto, la solicitud POST está protegida de alguna manera y, a continuación, verificada por el receptor. Por ejemplo, WebHooks de GitHub incluye un encabezado HTTP X-Hub-Signature con un hash del cuerpo de la solicitud que comprueba la implementación del receptor para que no tenga que preocuparse por él.

El flujo de WebHook suele ser similar al siguiente:

  • El remitente del WebHook expone eventos a los que un cliente puede suscribirse. Los eventos describen los cambios observables en el sistema, por ejemplo: que se ha insertado un nuevo elemento de datos, que se ha completado un proceso o algo más.

  • El receptor de WebHook se suscribe mediante el registro de un WebHook que consta de cuatro cosas:

    1. Un URI para donde se debe publicar la notificación de eventos en forma de una solicitud HTTP POST;

    2. Conjunto de filtros que describen los eventos concretos para los que se debe desencadenar el WebHook;

    3. Clave secreta que se usa para firmar la solicitud HTTP POST;

    4. Datos adicionales que se van a incluir en la solicitud HTTP POST. Por ejemplo, puede ser campos o propiedades de encabezado HTTP adicionales incluidos en el cuerpo de la solicitud HTTP POST.

  • Una vez que se produce un evento, se encuentran los registros de WebHook coincidentes y se envían las solicitudes HTTP POST. Normalmente, la generación de las solicitudes HTTP POST se reintenta varias veces si, por algún motivo, el destinatario no responde o la solicitud HTTP POST produce una respuesta de error.

Canalización de procesamiento de WebHooks

La canalización de procesamiento de WebHooks de Microsoft ASP.NET para WebHooks entrantes tiene este aspecto:

ASP.NET WebHooks Processing Pipeline

Los dos conceptos clave son receptores y controladores:

  • Los receptores son responsables de controlar el tipo concreto de WebHook de un remitente determinado y de aplicar comprobaciones de seguridad para asegurarse de que la solicitud de WebHook realmente procede del remitente previsto.

  • Los controladores suelen ser donde el código de usuario se ejecuta procesando el WebHook determinado.

En los nodos siguientes, estos conceptos se describen en más detalle.