Recapito di eventi webhook

Articolo
10/18/2023

I webhook sono uno dei molti modi per ricevere eventi da Griglia di eventi di Azure. Quando un nuovo evento è pronto, il servizio Griglia di eventi esegue il pos di una richiesta HTTP all'endpoint configurato con le informazioni sull'evento nel corpo della richiesta.

Analogamente a molti altri servizi che supportano i webhook, Griglia di eventi richiede la dimostrazione della proprietà dell'endpoint del webhook prima dell'inizio del recapito di eventi a tale endpoint. Questo requisito impedisce a un utente malintenzionato di sovraccaricare l'endpoint con eventi.

Convalida degli endpoint con eventi di Griglia di eventi

Quando si usa uno dei tre servizi di Azure seguenti, l'infrastruttura di Azure gestisce automaticamente questa convalida:

App per la logica di Azure con il connettore Griglia di eventi
Automazione di Azure tramite webhook
Funzioni di Azure con il trigger Griglia di eventi

Se si usa un altro tipo di endpoint, ad esempio un trigger HTTP basato su una funzione di Azure, il codice dell'endpoint deve partecipare a un handshake di convalida con Griglia di eventi. Griglia di eventi supporta due modalità di convalida della sottoscrizione.

Handshake sincrono: al momento della creazione della sottoscrizione di eventi, Griglia di eventi invia un evento di convalida della sottoscrizione all'endpoint. Lo schema di questo evento è simile a qualsiasi altro evento di Griglia di eventi. La parte di dati dell'evento include una proprietà validationCode. L'applicazione verifica che la richiesta di convalida sia per una sottoscrizione di eventi prevista e restituisce il codice di convalida nella risposta in modo sincrono. Questo meccanismo di handshake è supportato in tutte le versioni di Griglia di eventi.
Handshake asincrono: in alcuni casi, non è possibile restituire in modo sincrono l'oggetto validationCode in risposta. Se ad esempio si usa un servizio di terze parti,Zapier o IFTTT, non è possibile rispondere con il codice di convalida a livello di codice.

Griglia di eventi supporta un handshake di convalida manuale. Se si sta creando una sottoscrizione di eventi con un SDK o uno strumento che usa l'API 2018-05-01-preview o versione successiva, Griglia di eventi invia una proprietà validationUrl nella parte di dati dell'evento di convalida della sottoscrizione. Per completare l'handshake, trovare l'URL nei dati dell'evento ed eseguire una richiesta GET per tale URL. È possibile usare un client REST o un Web browser.

L'URL specificato è valido per 10 minuti. Durante questo periodo, lo stato di provisioning della sottoscrizione di eventi è AwaitingManualAction. Se si non completata la convalida manuale entro 10 minuti, lo stato di provisioning è impostato su Failed. È possibile creare la sottoscrizione all'evento nuovamente prima di avviare la convalida manuale.

Questo meccanismo di autenticazione richiede anche che l'endpoint del webhook restituisca il codice di stato HTTP 200 per sapere che la richiesta POST per l'evento di convalida è stata accettata prima di passare alla modalità di convalida manuale. In altre parole, se l'endpoint restituisce 200 ma non restituisce una risposta di convalida in modo sincrono, viene eseguita la transizione della modalità di convalida a manuale. Se è presente un get sull'URL di convalida entro 10 minuti, l'handshake di convalida viene considerato corretto.

Nota

L'uso di certificati autofirmati per la convalida non è supportato. Usare un certificato firmato da un'autorità di certificazione commerciale (CA, Certificate Authority).

Dettagli di convalida

In fase di creazione/aggiornamento della sottoscrizione di eventi, Griglia di eventi inserisce un evento di convalida della sottoscrizione nell'endpoint di destinazione.
L'evento contiene un valore aeg-event-type: SubscriptionValidationdi intestazione .
Il corpo dell'evento ha lo stesso schema degli altri eventi di Griglia di eventi.
La eventType proprietà dell'evento è Microsoft.EventGrid.SubscriptionValidationEvent.
La data proprietà dell'evento include una validationCode proprietà con una stringa generata in modo casuale. Ad esempio: validationCode: acb13….
I dati dell'evento includono anche una proprietà validationUrl con un URL che è possibile usare per convalidare manualmente la sottoscrizione.
La matrice contiene solo l'evento di convalida. Gli altri eventi vengono inviati in una richiesta separata dopo che è stato rimandato il codice di convalida.
Gli SDK del piano dati EventGrid hanno classi corrispondenti ai dati degli eventi di convalida della sottoscrizione e alla risposta di convalida della sottoscrizione.

Un esempio di SubscriptionValidationEvent è mostrato di seguito:

[
  {
    "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"
  }
]

Per dimostrare la proprietà dell'endpoint, ripetere il codice di convalida nella validationResponse proprietà , come illustrato nell'esempio seguente:

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

Seguire anche una di queste operazioni:

È necessario restituire un codice di stato della risposta HTTP 200 OK . HTTP 202 Accepted non viene riconosciuto come una risposta valida di convalida della sottoscrizione di Griglia di eventi. La richiesta HTTP deve essere completata entro 30 secondi. Se l'operazione non termina entro 30 secondi, verrà annullata e potrà essere ritentata dopo 5 secondi. Se tutti i tentativi hanno esito negativo, viene considerato come errore di handshake di convalida.

Il fatto che l'applicazione sia pronta a gestire e restituire il codice di convalida indica che è stata creata la sottoscrizione di eventi e si prevede di ricevere l'evento. Si supponga che lo scenario in cui non sia supportata la convalida dell'handshake e che un hacker sappia l'URL dell'applicazione. L'hacker può creare un argomento e una sottoscrizione di eventi con l'URL dell'applicazione e iniziare a condurre un attacco DoS all'applicazione inviando molti eventi. La convalida dell'handshake impedisce che ciò accada.

Si supponga di avere già implementato la convalida nell'app perché sono state create sottoscrizioni di eventi personalizzate. Anche se un hacker crea una sottoscrizione di eventi con l'URL dell'app, l'implementazione corretta dell'evento della richiesta di convalida verifica la presenza dell'intestazione aeg-subscription-name nella richiesta per verificare che si tratti di una sottoscrizione di eventi riconosciuta.

Anche dopo l'implementazione corretta dell'handshake, un hacker può inondare l'app (già convalidata la sottoscrizione di eventi) replicando una richiesta che sembra provenire da Griglia di eventi. Per evitare questo, è necessario proteggere il webhook con l'autenticazione Microsoft Entra. Per altre informazioni, vedere Recapitare eventi agli endpoint protetti da Microsoft Entra.
In alternativa, è possibile convalidare manualmente la sottoscrizione inviando una richiesta GET all'URL di convalida. La sottoscrizione dell'evento rimane nello stato in sospeso fino a quando non viene convalidata. L'URL di convalida usa la porta 553. Se le regole del firewall bloccano la porta 553, è necessario aggiornare le regole per un handshake manuale riuscito.

Nella convalida dell'evento di convalida della sottoscrizione, se si identifica che non si tratta di una sottoscrizione di eventi per cui si prevedono eventi, non restituirete una risposta 200 o nessuna risposta. Di conseguenza, la convalida non riesce.

Per un esempio di gestione dell'handshake di convalida della sottoscrizione, vedere un esempio C#.

Convalida degli endpoint con CloudEvents v1.0

CloudEvents v1.0 implementa la propria semantica di protezione dall'uso improprio tramite il metodo HTTP OPTIONS. Per altre informazioni, leggere qui. Quando si usa lo schema CloudEvents per l'output, Griglia di eventi usa la protezione dagli abusi di CloudEvents v1.0 al posto del meccanismo di eventi di convalida di Griglia di eventi.

Compatibilità dello schema di eventi

Quando viene creato un argomento, viene definito uno schema di eventi in ingresso. Inoltre, quando viene creata una sottoscrizione, viene definito uno schema di eventi in uscita. Nella tabella seguente viene illustrata la compatibilità consentita durante la creazione di una sottoscrizione.

Schema di eventi in ingresso	Schema eventi in uscita	Supportata
Schema di griglia di eventi	Schema di griglia di eventi	Sì
	Schema eventi cloud v1.0	Sì
	Schema di input personalizzato	No
Schema eventi cloud v1.0	Schema di griglia di eventi	No
	Schema eventi cloud v1.0	Sì
	Schema di input personalizzato	No
Schema di input personalizzato	Schema di griglia di eventi	Sì
	Schema eventi cloud v1.0	Sì
	Schema di input personalizzato	Sì

Passaggi successivi

Vedere l'articolo seguente per informazioni su come risolvere i problemi relativi alle convalide delle sottoscrizioni di eventi: Risolvere i problemi relativi alle convalide delle sottoscrizioni di eventi.