Como hospedar um destino de webhook

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

Veiculação do Cloud Functions x Knative

O Cloud Functions e a exibição do Knative fornecem boas soluções para hospedar seus destinos de webhook. Geralmente, o Cloud Functions é rápido de configurar, ótimo para protótipos e ideal para fluxos de trabalho de menor volume. A disponibilização do Knative oferece mais flexibilidade e é capaz de lidar com volumes maiores com simultaneidade.

Use a veiculação do Knative se:

  • você estiver usando linguagens ou ambientes de execução não compatíveis com o Cloud Functions;
  • você quiser mais tempo limite de solicitação (até 15 minutos);
  • você espera um grande volume e precisa de simultaneidade (80 solicitações simultâneas ou mais por instância de contêiner).

Como criar um destino de webhook na veiculação do Knative

Com o Knative, é 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ê processe apenas dados de fontes autorizadas.

Para verificar a solicitação, você precisa armazenar sua cópia do secret como uma variável de ambiente ou usar algum tipo de sistema de gerenciamento de chaves. Cada solicitação precisa ter um secret ou token nos cabeçalhos de solicitação 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

A veiculação do Knative 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 provedor de webhooks ou veiculação Knative, você precisará usar um produto que permita concluir o processamento de forma assíncrona, como Pub/Sub ou Cloud Tasks. 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 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.
Dados de armazenamento 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 teste sempre que um novo código for confirmado no GitHub.

A seguir