Panoramica dei webhook ASP.NET

I webhook sono 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.

Grazie alla loro 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. Ad esempio, un WebHook può indicare che un file è stato modificato in Dropbox oppure che è stato eseguito il commit di una modifica del codice in GitHub o che è stato avviato un pagamento in PayPal o che è 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 un numero qualsiasi di provider webhook. Viene fornita come predefinita con il supporto per Dropbox, GitHub, Bitbucket, MailChimp, PayPal, Pusher, Salesforce, Slack, Stripe, Trello,WordPress e Zendesk, ma è facile aggiungere supporto per altro.

• Sul lato 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 notificare quando si verifica un evento.

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 i 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 uno schema 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 del webhook, incluse informazioni sull'evento che causa il trigger del WebHook. Ad esempio, un corpo della richiesta POST di WebHook da GitHub è simile al seguente in seguito all'apertura di un nuovo problema in un repository specifico:

{
  "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 provengano effettivamente dal mittente previsto, la richiesta POST viene protetta in qualche modo e quindi verificata dal ricevitore. Ad esempio, i webhook GitHub includono un'intestazione HTTP X-Hub-Signature con un hash del corpo della richiesta controllato dall'implementazione del ricevitore in modo da non doversi preoccupare.

Il flusso webhook è in genere simile al seguente:

• 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 dati, che un processo è stato completato o un altro elemento.

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

  1. URI per cui la notifica degli eventi deve essere registrata sotto forma di richiesta HTTP POST;

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

  3. Una chiave privata usata per firmare la richiesta HTTP POST;

  4. Dati aggiuntivi da includere nella richiesta HTTP POST. Può ad esempio trattarsi di ulteriori campi di intestazione HTTP o proprietà inclusi nel corpo della richiesta HTTP POST.

• Una volta che si verifica un evento, vengono trovate le registrazioni webhook corrispondenti e vengono inviate richieste HTTP POST. 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 genera una risposta di errore.

Pipeline di elaborazione webhook

La pipeline di elaborazione webhook di Microsoft ASP.NET per i webhook in ingresso è simile alla seguente:

I due concetti chiave sono ricevitori e gestori:

• I ricevitori sono responsabili della gestione del particolare tipo di webhook da un determinato mittente e dell'applicazione dei controlli di sicurezza per garantire che la richiesta webhook provengano effettivamente dal mittente previsto.

• I gestori sono in genere in cui il codice utente esegue l'elaborazione del webhook specifico.

Nei nodi seguenti questi concetti sono descritti in altri dettagli.