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 pubblicazione Knative

Sia le funzioni Cloud Run sia il servizio Knative forniscono ottime soluzioni per ospitare i tuoi target webhook. In genere, le funzioni Cloud Run sono facili da configurare, ottime per la prototipazione e ideali per i flussi di lavoro con volumi ridotti. Knative serving offre una maggiore flessibilità ed è in grado di gestire volumi più grandi con la concorrenza.

Utilizza Knative serving se:

  • Utilizzi linguaggi o runtime non supportati nelle funzioni Cloud Run
  • Vuoi timeout delle richieste più lunghi (fino a 15 minuti)
  • Prevedi un volume elevato e hai bisogno di concorrenza (80 richieste in parallelo o più per istanza di contenitore)

Creazione di un target webhook in Knative serving

Con la pubblicazione Knative, puoi definire un target webhook in qualsiasi lingua scelga. Devi solo creare un endpoint HTTP che possa 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 riportato sopra, la pagina di indice dell'URL è configurata per accettare solo richieste POST e si aspetta che i dati vengano inviati 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, questo viene fatto inviando un tipo 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 codice potrebbe avere il seguente aspetto:

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

Un target webhook è un URL aperto e pubblico. La maggior parte dei servizi fornisce un token o un segreto per garantire che le richieste in arrivo provengano da servizi autorizzati. Poiché l'URL è pubblico, non puoi impedire tentativi malintenzionati di inviare dati al target dell'webhook. Tuttavia, l'utilizzo di token o segreti ti garantisce di elaborare solo i dati provenienti da fonti autorizzate.

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

Quando memorizzi la copia del secret come variabile di ambiente, ogni richiesta deve avere un secret o un token negli header 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 fornitore di webhook non supporta un segreto o un altro meccanismo di autenticazione, chiunque disponga dell'URL del target dell'webhook potrà inviare messaggi. In questo caso, l'implementazione dell'webhook dovrebbe essere sicura da esporre all'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 integrati se viene generata una risposta di errore, ad esempio un codice di stato HTTP 4xx o 5xx, pertanto dovrai restituire un codice di stato di esito positivo (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 dei timeout. Il valore più breve dei due verrà applicato alla tua richiesta. Se l'elaborazione dei dati supera il tempo assegnato dal servizio Knative o dal provider di webhook, devi 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 fornitore di webhook e continuare l'elaborazione senza preoccuparti del timeout. Sono anche ottime opzioni per gestire errori e tentativi di nuovo.

Pattern comuni dei webhook

Tipo Esempi
Trasmissione dati Invio di una notifica tramite Firebase Cloud Messaging ogni volta che viene chiamato l'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 nuovo codice in GitHub.

Passaggi successivi