Hosting di destinazioni di webhook

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

Funzioni Cloud Run e Cloud Run

Sia le funzioni Cloud Run sia Cloud Run offrono ottime soluzioni per ospitare i target degli 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. Cloud Run offre maggiore flessibilità ed è in grado di gestire volumi più elevati con la concorrenza.

Utilizza Cloud Run se:

  • Utilizzi 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 richieste in parallelo per istanza)

Creazione di una destinazione di webhook in Cloud Run

Con Cloud Run, puoi definire una destinazione di webhook in qualsiasi lingua. 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 dei tentativi 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 Cloud Run sia il provider di webhook hanno dei timeout. Il valore più breve tra i due verrà applicato alla tua richiesta. Se l'elaborazione dei dati supera il tempo assegnato da Cloud Run 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 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 Esecuzione di azioni su Dialogflow, pubblicazione di risposte su Twitter o esecuzione del push nell'ambiente di staging ogni volta che viene eseguito il commit di nuovo codice in GitHub.

Passaggi successivi