Panoramica dei webhook ASP.NET

WebHooks è un modello HTTP leggero che fornisce un semplice modello pub/sub per collegare le API Web e i servizi SaaS. Quando si verifica un evento in un servizio, viene inviata una notifica sotto forma di richiesta HTTP POST ai sottoscrittori registrati. La richiesta POST contiene informazioni sull'evento che consente al ricevitore di agire di conseguenza.

A causa della semplicità, i webhook sono già esposti da un numero elevato di servizi, tra cui Dropbox, GitHub, Bitbucket, MailChimp, PayPal, Slack, Stripe, Trello e molti altri ancora. Ad esempio, un webhook può indicare che un file è stato modificato in Dropbox o è stato eseguito il commit di una modifica del codice in GitHub oppure è stato avviato un pagamento in PayPal oppure è stata creata una carta in Trello. Le possibilità sono infinite!

Microsoft ASP.NET WebHook semplifica l'invio e la ricezione di webhook come parte dell'applicazione ASP.NET:

• Sul lato ricevente, fornisce un modello comune per la ricezione e l'elaborazione di WebHook da qualsiasi numero di provider di WebHook. Viene fornito con supporto per Dropbox, GitHub, Bitbucket, MailChimp, PayPal, Pusher, Salesforce, Slack, Stripe, Trello, WordPress e Zendesk, ma è facile aggiungere il supporto per altri servizi.

• Sul lato di invio fornisce supporto per la gestione e l'archiviazione delle sottoscrizioni, nonché per l'invio di notifiche degli eventi al set corretto di sottoscrittori. In questo modo è possibile definire un set personalizzato di eventi che i sottoscrittori possono sottoscrivere e notificarli quando si verificano eventi.

Le due parti possono essere usate insieme o separate a seconda dello scenario. Se è sufficiente ricevere webhook da altri servizi, è possibile usare solo la parte ricevitore; se si vogliono esporre solo webhook per consentire ad altri utenti di utilizzarli, è possibile farlo.

Il codice è destinato API Web ASP.NET 2 e ASP.NET MVC 5 ed è disponibile come OSS in GitHub.

Panoramica dei webhook

I webhook sono un modello che significa che varia il modo in cui viene usato dal servizio al servizio, ma l'idea di base è la stessa. È possibile considerare i webhook come un semplice modello pub/sub in cui un utente può sottoscrivere eventi che si verificano altrove. Le notifiche degli eventi vengono propagate come richieste HTTP POST contenenti informazioni sull'evento stesso.

In genere la richiesta HTTP POST contiene un oggetto JSON o i dati del modulo HTML determinati dal mittente webhook, incluse informazioni sull'evento che causa l'attivazione del webhook. Ad esempio, un corpo della richiesta POST webhook da GitHub è simile al seguente in seguito all'apertura di un nuovo problema in un particolare repository:

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

Per garantire che il webhook provenga effettivamente dal mittente previsto, la richiesta POST viene protetta in qualche modo e quindi verificata dal ricevitore. Ad esempio, GitHub WebHooks include un' X-Hub-Signature intestazione HTTP con un hash del corpo della richiesta, che è verificato dall'implementazione del ricevitore in modo che tu non debba preoccuparti.

Il flusso webhook avviene più o meno così:

• Il mittente del webhook espone gli eventi a cui un client può sottoscrivere. Gli eventi descrivono le modifiche osservabili al sistema, ad esempio che è stato inserito un nuovo elemento di dati, che un processo è stato completato o qualcos'altro.

• Il ricevitore webhook sottoscrive registrando un webhook costituito da quattro elementi:

  1. URI per cui la notifica dell'evento deve essere inserita sotto forma di richiesta HTTP POST;

  2. Set di filtri che descrivono gli eventi specifici per i quali deve essere generato il webhook;

  3. Chiave privata usata per firmare la richiesta HTTP POST;

  4. Dati aggiuntivi che devono essere inclusi nella richiesta HTTP POST. Ad esempio, possono essere campi o proprietà di intestazione HTTP aggiuntivi inclusi nel corpo della richiesta HTTP POST.

• Quando si verifica un evento, vengono trovate le registrazioni webhook corrispondenti e le richieste HTTP POST vengono inviate. In genere, la generazione delle richieste HTTP POST viene ritentata più volte se per qualche motivo il destinatario non risponde o la richiesta HTTP POST restituisce una risposta di errore.

Pipeline di elaborazione Webhook

La pipeline di elaborazione dei WebHook di Microsoft ASP.NET per i WebHook in ingresso è la seguente:

I due concetti chiave sono i ricevitori e i gestori:

• I ricevitori sono responsabili della gestione della specifica variante del WebHook da un determinato mittente e dell'applicazione dei controlli di sicurezza per garantire che le richieste WebHook siano effettivamente provenienti dal mittente previsto.

• In genere, i gestori sono i punti in cui il codice utente viene eseguito per elaborare lo specifico WebHook.

Nei nodi seguenti questi concetti sono descritti in dettaglio.