Hosting di destinazioni webhook

Questa guida mostra come ospitare una destinazione di webhook in un servizio Cloud Run.

Confronto tra Cloud Functions e Cloud Run

Cloud Functions e Cloud Run forniscono entrambe ottime soluzioni per l'hosting dei target dei webhook. In generale, Cloud Functions è veloce da configurare, ideale per la prototipazione e per flussi di lavoro a basso volume. Cloud Run offre maggiore flessibilità ed è in grado di gestire volumi più grandi in contemporanea.

Utilizza Cloud Run se:

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

Creazione di una destinazione webhook in Cloud Run

Con Cloud Run, puoi definire un target per il webhook in qualsiasi linguaggio scelto. 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 di indice dell'URL è configurata per accettare solo richieste POST e prevede che i dati vengano consegnati 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. Di solito, questo viene fatto inviando un qualche tipo di token, messaggio o secret e aspettando una risposta valida. Dovrai richiedere questi requisiti al fornitore di servizi. Utilizzando lo stesso esempio precedente, il risultato potrebbe essere il seguente:

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

Dopo che il provider ha verificato la tua proprietà, dovrai aggiungere anche l'autorizzazione.

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 inviare dati alla destinazione del webhook. Tuttavia, l'utilizzo di token o secret garantisce l'elaborazione solo dei dati provenienti 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 qualche tipo di sistema di gestione delle chiavi.

Quando archivi la tua copia del secret come variabile di ambiente, ogni richiesta dovrebbe avere un secret o un token nelle intestazioni della richiesta o nel payload JSON e devi verificarlo 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 del webhook sarà in grado di inviare i messaggi. In questo caso, l'implementazione del webhook deve essere sicura e visibile sulla rete internet pubblica.

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 integrati per i nuovi tentativi se c'è una risposta di errore, ad esempio un codice di stato HTTP 4xx o 5xx, quindi dovrai restituire un codice di stato di operazione riuscita (2xx) per comunicare al servizio che l'evento è stato elaborato correttamente.

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

Timeout

Sia Cloud Run che il provider di webhook hanno dei timeout. Il più breve dei due sarà valido per la tua applicazione. Se l'elaborazione dei dati supera il tempo assegnato da Cloud Run o dal provider di webhook, devi utilizzare un prodotto che consenta di completare l'elaborazione in modo asincrono, ad esempio Pub/Sub o Cloud Tasks. Questi prodotti consentono di trasferire rapidamente i dati, restituire immediatamente una risposta di operazione riuscita al provider dei webhook e continuare l'elaborazione senza il problema di timeout. Sono anche ottime opzioni per la gestione di errori e nuovi tentativi.

Pattern comuni dei webhook

Tipo Esempi
Inoltro 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 le azioni su Dialogflow, pubblicare risposte su Twitter o eseguire il push nell'ambiente di gestione temporanea ogni volta che viene eseguito il commit di nuovo codice in GitHub.

Passaggi successivi