Como hospedar destinos de webhooks

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

Funções do Cloud Run x Cloud Run

As funções do Cloud Run e o Cloud Run fornecem boas soluções para hospedar seus destinos de webhooks. 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 Cloud Run oferece mais flexibilidade e é capaz de lidar com volumes maiores com simultaneidade.

Use o Cloud Run se:

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

Como criar um destino de webhook no Cloud Run

Com o Cloud Run, é possível definir um destino de webhook em qualquer linguagem. Você só precisa 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ê processe apenas 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)

Tempo limite

O Cloud Run e o provedor de webhooks têm tempos limite. O menor deles será aplicado ao seu aplicativo. Se o processamento de dados exceder o tempo especificado pelo Cloud Run ou pelo provedor de webhooks, você precisará usar um produto que permita concluir o processamento de forma assíncrona, como Pub/Sub ou Cloud Tasks (links em inglês). Esses produtos permitem que você entregue os dados rapidamente, retorne imediatamente uma resposta de sucesso ao provedor de webhooks e continue o processamento sem a preocupação de 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