Alojamento de um destino de webhook

Este guia mostra como alojar um destino de webhook num serviço de fornecimento do Knative.

Funções do Cloud Run vs. serviço Knative

As funções do Cloud Run e o Knative Serving oferecem boas soluções para alojar os destinos dos webhooks. Geralmente, as funções do Cloud Run são rápidas de configurar, são boas para a criação de protótipos e são ideais para fluxos de trabalho de menor volume. O Knative Serving oferece mais flexibilidade e consegue processar volumes maiores com simultaneidade.

Use o Knative serving se:

  • Está a usar idiomas ou tempos de execução não suportados nas funções do Cloud Run
  • Quiser limites de tempo limite de pedidos mais longos (até 15 minutos)
  • Está a prever um volume elevado e precisa de concorrência (80 pedidos simultâneos ou mais por instância do contentor)

Criar um destino de webhook no Knative serving

Com o Knative serving, pode definir um destino de webhook em qualquer idioma que escolher. Só tem de criar um ponto final HTTP que possa aceitar os dados. Normalmente, isto é feito com um POST, por exemplo:

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

No exemplo acima, a página de índice do URL está configurada para aceitar apenas pedidos POST e espera que os dados sejam enviados através de um payload JSON.

Integração com o fornecedor de webhook

A maioria dos serviços que fornecem callbacks HTTP requer que valide a propriedade do URL. Normalmente, isto é feito através do envio de algum tipo de token, mensagem ou segredo e esperando uma resposta válida. Tem de obter estes requisitos junto do fornecedor de serviços. Usando o mesmo exemplo acima, isto pode ter o seguinte aspeto:

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

Depois de o fornecedor validar a sua propriedade, também tem de adicionar a autorização no seu lado.

Autorizar pedidos

Um destino de webhook é um URL aberto e público. A maioria dos serviços fornece um token ou um segredo para garantir que os pedidos recebidos são de serviços autorizados. Uma vez que o URL é público, não pode impedir tentativas maliciosas de enviar dados para o destino do webhook. No entanto, a utilização de tokens ou segredos garante que apenas processa dados de origens autorizadas.

Para validar o pedido, pode configurar segredos ou armazenar a sua cópia do segredo como uma variável de ambiente ou através de algum tipo de sistema de gestão de chaves.

Quando armazena a sua cópia do segredo como uma variável de ambiente, cada pedido deve ter um segredo ou um token nos cabeçalhos do pedido ou na carga útil JSON, e tem de verificá-lo para garantir que a origem é válida.

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

Se o fornecedor de webhook não suportar um segredo ou outro mecanismo de autenticação, qualquer pessoa com o URL do destino do webhook vai poder enviar mensagens. Neste caso, a implementação do webhook deve ser segura para exposição à Internet pública.

Responder a pedidos

A maioria dos serviços requer que responda a um pedido dentro de um período definido, conforme especificado pelo serviço. Alguns webhooks têm métodos de repetição incorporados se houver uma resposta de erro, como um código de estado HTTP de 4xx ou 5xx, pelo que tem de devolver um código de estado com êxito (2xx) para informar o serviço de que o evento foi processado corretamente.

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

Limites de tempo

O Knative serving e o fornecedor de webhooks têm tempos limite. O período mais curto dos dois aplica-se à sua candidatura. Se o processamento de dados exceder o tempo atribuído pelo Knative serving ou pelo fornecedor de webhooks, tem de usar um produto que lhe permita concluir o processamento de forma assíncrona, como o Pub/Sub ou o Cloud Tasks. Estes produtos permitem-lhe transferir rapidamente os dados, devolver imediatamente uma resposta de êxito ao fornecedor de webhooks e continuar o processamento sem se preocupar com o limite de tempo. Estas também são boas opções para processar falhas e novas tentativas.

Padrões de webhooks comuns

Tipo Exemplos
Transmissão de dados Enviar uma notificação através do Firebase Cloud Messaging sempre que o webhook é chamado.
Armazenar dados Armazenar os dados no BigQuery para análise posterior.
Acionamento de ações Preencher ações no Dialogflow, publicar respostas no Twitter ou enviar para o seu ambiente de preparação sempre que for enviado novo código no GitHub.

O que se segue?