Como hospedar um destino de webhook

Neste guia, mostramos como hospedar um destino de webhook em um serviço do Knative serving.

Cloud Run functions x Knative serving

O Cloud Run functions e o Knative serving são ótimas soluções para hospedar destinos de webhook. Geralmente, as funções do Cloud Run são rápidas de configurar, ótimas para protótipos e ideais para fluxos de trabalho de menor volume. O Knative serving oferece mais flexibilidade e é capaz de lidar com volumes maiores com simultaneidade.

Use o Knative serving se:

  • você está usando linguagens ou ambientes de execução não compatíveis com as funções do Cloud Run;
  • você quer mais tempo limite de solicitação (até 15 minutos);
  • você está aguardando um volume grande e precisa de simultaneidade (80 solicitações simultâneas ou mais por instância de contêiner).

Como criar um destino de webhook no Knative serving

Com o Knative serving, é possível definir um destino de webhook em qualquer linguagem. Basta criar um endpoint HTTP que aceite os dados. Normalmente, isso é 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 solicitações POST e espera que os dados sejam entregues por meio de um payload JSON.

Como integrar com o provedor de webhook

A maioria dos serviços que fornecem retornos de chamada HTTP exige que você confirme a propriedade do URL. Isso geralmente é feito enviando algum tipo de token, mensagem ou secret e esperando uma resposta válida. Você precisará conseguir esses requisitos junto ao provedor de serviços. Usando o mesmo exemplo acima, isso seria semelhante a:

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

Depois que o provedor confirmar sua propriedade, você também precisará adicionar autorização.

Como autorizar solicitações

Um destino de webhook é um URL aberto e público. A maioria dos serviços fornece um token ou um secret para garantir que as solicitações recebidas sejam de serviços autorizados. Como o URL é público, não é possível impedir tentativas mal-intencionadas de enviar dados para o destino de webhook. No entanto, o uso de tokens ou secrets garante que você só processe os dados de fontes autorizadas.

Para verificar a solicitação, configure secrets, armazene sua cópia como uma variável de ambiente ou use algum tipo de sistema de gerenciamento de chaves.

Ao armazenar sua cópia do secret como uma variável de ambiente, cada solicitação precisa ter um secret ou token nos cabeçalhos ou no payload JSON, e você precisa verificá-lo para garantir que a origem seja válida.

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

Se o provedor do webhook não for compatível com um secret ou outro mecanismo de autenticação, qualquer pessoa com o URL do destino do webhook poderá enviar mensagens. Nesse caso, a implementação do webhook precisa ser segura para expor à Internet pública.

Como responder a solicitações

A maioria dos serviços exige que você responda a uma solicitação dentro de um período de tempo definido, conforme especificado pelo serviço. Alguns webhooks têm métodos de repetição integrados para situações de resposta a erros, como um código de status HTTP de 4xx ou 5xx. Portanto, você precisará retornar um código de status bem-sucedido (2xx) para informar ao serviço que o evento foi processado corretamente.

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

Tempos limite

O Knative serving e o provedor de webhooks têm tempos limite. O menor deles será aplicado ao aplicativo. Se o processamento de dados exceder o tempo alocado pelo Knative serving ou pelo provedor de webhooks, você terá que usar um produto que permita concluir o processamento de modo assíncrono, como o Pub/Sub ou o Cloud Tasks. Com esses produtos, você consegue entregar dados rapidamente, retornar imediatamente uma resposta de sucesso ao provedor de webhooks e continuar o processamento sem se preocupar com o tempo limite. Eles também são boas opções para lidar com falhas e novas tentativas.

Padrões comuns de webhooks

Tipo Exemplos
Dados de redirecionamento Enviar uma notificação por meio do Firebase Cloud Messaging sempre que o webhook for chamado.
Como armazenar dados Armazenar os dados no BigQuery para análise posterior.
Ações de acionamento Realizar ações no Dialogflow, postar respostas no Twitter ou enviar para o ambiente de preparo sempre que um novo código for confirmado no GitHub.

A seguir