Hosting di una destinazione di webhook

Questa guida mostra come configurare l'hosting di una destinazione di webhook in un servizio Knative serving.

Funzioni Cloud Run e Knative Serving

Cloud Run Functions e Knative Serving forniscono entrambe buone soluzioni per ospitare le destinazioni webhook. In genere, Cloud Run Functions è facile da configurare, è ideale per la prototipazione e per i workflow a basso volume. Knative Serving offre maggiore flessibilità ed è in grado di gestire volumi più grandi con la concorrenza.

Utilizza Knative serving se:

  • Stai utilizzando linguaggi o runtime non supportati in Cloud Run Functions
  • Vuoi timeout delle richieste più lunghi (fino a 15 minuti)
  • Prevedi un volume elevato e hai bisogno di concorrenza (80 o più richieste simultanee per istanza di container)

Creazione di una destinazione webhook in Knative serving

Utilizzando Knative Serving, puoi definire una destinazione webhook in qualsiasi lingua tu scelga. Devi solo creare un endpoint HTTP in grado di accettare i dati. In genere, questa operazione viene eseguita con un POST, ad esempio:

@app.route('/', methods=['POST'])
def index():
    data = request.get_json()

Nell'esempio precedente, la pagina indice dell'URL è configurata per accettare solo richieste POST e prevede che i dati vengano forniti tramite un payload JSON.

Integrazione con il provider webhook

La maggior parte dei servizi che forniscono callback HTTP richiede la verifica della proprietà dell'URL. In genere, questa operazione viene eseguita inviando una sorta di token, messaggio o segreto e aspettandosi una risposta valida. Dovrai ottenere questi requisiti dal fornitore di servizi. Utilizzando lo stesso esempio riportato sopra, il risultato potrebbe essere il seguente:

def index():
    data = request.get_json()
    return data['challenge']

Dopo che il fornitore avrà verificato la tua proprietà, dovrai aggiungere l'autorizzazione anche da parte tua.

Autorizzazione delle richieste

Una destinazione webhook è un URL aperto e pubblico. La maggior parte dei servizi fornisce un token o un segreto per garantire che le richieste in entrata provengano da servizi autorizzati. Poiché l'URL è pubblico, non puoi impedire tentativi dannosi di invio di dati alla destinazione del webhook. Tuttavia, l'utilizzo di token o segreti garantisce l'elaborazione dei dati solo da origini autorizzate.

Per verificare la richiesta, puoi configurare i secret o archiviare la tua copia del secret come variabile di ambiente o utilizzando un sistema di gestione delle chiavi.

Quando memorizzi la tua copia del secret come variabile di ambiente, ogni richiesta deve avere un secret o un token nelle intestazioni della richiesta o nel payload JSON e devi controllarlo per assicurarti che l'origine sia valida.

def index():
    request_secret = request.headers['Secret']
    if request_secret != os.environ['SECRET']:
        return ('Unauthorized', 401)

Se il provider webhook non supporta un secret o un altro meccanismo di autenticazione, chiunque abbia l'URL della destinazione webhook potrà inviare messaggi. In questo caso, l'implementazione del webhook deve essere sicura da esporre a internet pubblico.

Rispondere alle richieste

La maggior parte dei servizi richiede di rispondere a una richiesta entro un determinato periodo di tempo, come specificato dal servizio. Alcuni webhook hanno metodi di ripetizione dei tentativi integrati se si verifica una risposta di errore, ad esempio un codice di stato HTTP 4xx o 5xx, quindi devi restituire un codice di stato riuscito (2xx) per comunicare al servizio che l'evento è stato elaborato correttamente.

def index():
    data = request.get_json()
    return ('', 200)

Timeout

Sia Knative serving che il provider di webhook hanno timeout. Verrà applicato il periodo più breve tra i due. Se l'elaborazione dei dati supera il tempo assegnato dal servizio Knative o dal provider di webhook, dovrai utilizzare un prodotto che ti consenta di completare l'elaborazione in modo asincrono, ad esempio Pub/Sub o Cloud Tasks. Questi prodotti ti consentono di trasferire rapidamente i dati, restituire immediatamente una risposta di successo al provider di webhook e continuare l'elaborazione senza preoccuparti del timeout. Sono anche buone opzioni per la gestione di errori e tentativi.

Pattern comuni dei webhook

Tipo Esempi
Ritrasmissione dei dati Invio di una notifica tramite Firebase Cloud Messaging ogni volta che viene chiamato il webhook.
Archiviazione dei dati Archiviazione dei dati in BigQuery per analisi successive.
Azioni di attivazione Eseguire azioni su Dialogflow, pubblicare risposte su Twitter o eseguire il push nell'ambiente di staging ogni volta che viene eseguito il commit di un nuovo codice in GitHub.

Passaggi successivi