Vue d’ensemble des webhooks ASP.NET

WebHooks est un modèle HTTP léger qui fournit un modèle pub/sous-modèle simple pour le câblage entre les API web et les services SaaS. Lorsqu’un événement se produit dans un service, une notification est envoyée sous la forme d’une requête HTTP POST aux abonnés inscrits. La requête POST contient des informations sur l’événement, ce qui permet au récepteur d’agir en conséquence.

En raison de leur simplicité, les WebHooks sont déjà exposés par un grand nombre de services, notamment Dropbox, GitHub, Bitbucket, MailChimp, PayPal, Slack, Stripe, Trello et bien plus encore. Par exemple, un WebHook peut indiquer qu’un fichier a changé dans Dropbox, ou une modification du code a été validée dans GitHub, ou un paiement a été lancé dans PayPal ou une carte a été créée dans Trello. Les possibilités sont infinies !

Microsoft ASP.NET WebHooks facilite l’envoi et la réception de WebHooks dans le cadre de votre application ASP.NET :

• Côté réception, il fournit un modèle commun pour la réception et le traitement de WebHooks à partir de n’importe quel nombre de fournisseurs WebHook. Il est livré avec prise en charge de Dropbox, GitHub, Bitbucket, MailChimp, PayPal, Pusher, Salesforce, Slack, Stripe, Trello, WordPress et Zendesk, mais il est facile d'ajouter la prise en charge de plus de services.

• Côté envoi, il prend en charge la gestion et le stockage des abonnements, ainsi que pour l’envoi de notifications d’événements à l’ensemble approprié d’abonnés. Cela vous permet de définir votre propre ensemble d’événements auxquels les abonnés peuvent s’abonner et les avertir lorsque des choses se produisent.

Les deux parties peuvent être utilisées ensemble ou séparées en fonction de votre scénario. Si vous avez uniquement besoin de recevoir des WebHooks à partir d’autres services, vous pouvez utiliser uniquement le composant récepteur ; si vous souhaitez uniquement exposer des WebHooks pour que d’autres utilisateurs consomment, vous pouvez le faire uniquement.

Le code cible API Web ASP.NET 2 et ASP.NET MVC 5 et est disponible en tant que OSS sur GitHub.

Vue d’ensemble des WebHooks

WebHooks est un modèle qui signifie qu’il varie de la façon dont il est utilisé du service au service, mais l’idée de base est la même. Vous pouvez considérer les WebHooks comme un modèle de pub/sous-modèle simple où un utilisateur peut s’abonner à des événements qui se produisent ailleurs. Les notifications d’événements sont propagées en tant que requêtes HTTP POST contenant des informations sur l’événement lui-même.

En règle générale, la requête HTTP POST contient un objet JSON ou des données de formulaire HTML déterminées par l’expéditeur webHook, y compris des informations sur l’événement à l’origine du déclenchement du WebHook. Par exemple, un corps de requête POST WebHook de GitHub ressemble à ceci en raison d’un nouveau problème ouvert dans un référentiel particulier :

{
  "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,
      ...
  }
}

Pour vous assurer que le WebHook provient en effet de l’expéditeur prévu, la requête POST est sécurisée d’une certaine manière, puis vérifiée par le destinataire. Par exemple, GitHub WebHooks inclut un X-Hub-Signature en-tête HTTP avec un hachage du corps de la requête qui est vérifié par l'implémentation du récepteur afin que vous n'ayez pas à vous en soucier.

Le flux WebHook se présente généralement comme suit :

• L’expéditeur webHook expose les événements auxquels un client peut s’abonner. Les événements décrivent les modifications observables apportées au système, par exemple qu’un nouvel élément de données a été inséré, qu’un processus a terminé ou autre chose.

• Le récepteur WebHook s’abonne en inscrivant un WebHook composé de quatre éléments :

  1. URI pour lequel la notification d’événement doit être publiée sous la forme d’une requête HTTP POST ;

  2. Ensemble de filtres décrivant les événements particuliers pour lesquels le WebHook doit être déclenché ;

  3. Clé secrète utilisée pour signer la requête HTTP POST ;

  4. Données supplémentaires à inclure dans la requête HTTP POST. Par exemple, il peut s’agir de champs d’en-tête HTTP supplémentaires ou de propriétés inclus dans le corps de la requête HTTP POST.

• Une fois qu’un événement se produit, les inscriptions webHook correspondantes sont trouvées et les requêtes HTTP POST sont envoyées. En règle générale, la génération des requêtes HTTP POST est retentée plusieurs fois si, pour une raison quelconque, le destinataire ne répond pas ou si la requête HTTP POST génère une réponse d’erreur.

Pipeline de traitement des WebHooks

Le pipeline de traitement des WebHooks Microsoft ASP.NET pour les WebHooks entrants ressemble à ceci :

Les deux concepts clés sont les récepteurs et les gestionnaires :

• Les récepteurs sont responsables de la gestion de la saveur particulière du WebHook d’un expéditeur donné et de l’application de vérifications de sécurité pour s’assurer que la demande WebHook provient effectivement de l’expéditeur prévu.

• Les gestionnaires constituent généralement le point de départ où le code utilisateur est exécuté pour traiter un WebHook particulier.

Dans les nœuds suivants, ces concepts sont décrits plus en détail.