Gerenciamento

A simplicidade dos webhooks faz com que o peso do gerenciamento seja difícil de enxergar no começo. Mas, à medida que você continua usando webhooks e adicionando mais provedores e consumidores, o esforço de gerenciamento desse canal de comunicação começa a crescer.

Neste artigo, vamos passar pelos problemas de gerenciamento mais comuns ao trabalhar com webhooks e como resolvê-los com o Hookdeck. Cada problema abordado também inclui uma pequena seção de discussão para aprofundar o tema.

O peso do gerenciamento de webhooks

Inconsistência na configuração

O processo de configurar webhooks na plataforma de cada provedor é quase tão diverso quanto o número de provedores disponíveis. Isso dificulta transferir o conhecimento de configuração de um provedor para outro. Além disso, os provedores costumam mudar o fluxo de configuração de tempos em tempos.

Formatos de payload

O formato da mensagem também muda de provedor para provedor. Estrutura da mensagem, headers e formatos de dados (XML ou JSON) são todos diferentes. Essas variações exigem que o payload de cada provedor seja tratado de forma diferente.

Segurança

Existe ainda a questão da segurança, e cada provedor de webhooks lida com ela de um jeito. Embora as estratégias de segurança sejam padronizadas e limitadas (autenticação básica, tokens de API e verificação de assinatura, entre outras), os provedores dão suporte a um número variável delas.

Você pode saber mais sobre segurança de webhooks no nosso Guia completo de segurança de webhooks.

Múltiplos provedores e consumidores

É bem provável que você não vá processar webhooks de apenas um provedor. Por exemplo, você pode ter um site de e-commerce montado na Shopify enquanto processa pagamentos com a Stripe, então precisa trabalhar com webhooks de ambas. Por causa das diferenças na forma como os dois provedores lidam com webhooks, você vai precisar prever essas diferenças e, ao mesmo tempo, garantir que tudo funcione bem em conjunto dentro da sua aplicação.

E se você precisar trabalhar com múltiplos consumidores e rotear certas mensagens para um consumidor específico ou um conjunto deles?

Como gerenciar eventos de webhook “do jeito certo”?

Como a sua stack atual (provavelmente) se parece

Uma forma padrão e recomendada de lidar com webhooks é processá-los de forma assíncrona. O tipo mais comum de configuração de processamento assíncrono usa a arquitetura web-queue-worker. Ela ajuda a desacoplar o produtor e o consumidor de webhooks fazendo o buffer das mensagens em uma fila que fica entre os dois.

A fila ajuda a resolver problemas de timeout que surgem quando o consumidor está ocupado mas continua recebendo webhooks, e garante que as mensagens sejam persistentes e possam sofrer retry depois de erros.

Limitações da sua configuração atual

Embora a configuração descrita acima ajude a lidar com webhooks de forma mais confiável, ela não resolve de fato nenhum dos pesos de gerenciamento listados acima (exceto o caso de múltiplos consumidores).

Filas não têm recursos de transformação de mensagens que você possa configurar para converter mensagens de webhook em um formato alinhado à sua aplicação ou para harmonizar payloads diferentes. Você pode precisar acrescentar um API gateway para isso, mas vale notar que adicionar um API gateway é mais complexidade no sistema como um todo.

Você também continua tendo que cuidar dos diferentes formatos de autenticação e entender o componente de filas bem o suficiente para rotear mensagens aos consumidores certos.

Problemas comuns de gerenciamento de webhooks e as soluções do Hookdeck

Você precisa de um formato de payload específico

Problema

Você precisa receber o payload do webhook em um formato diferente.

Solução

O Hookdeck Transformation permite executar javascript sobre a requisição para atualizar o payload.

Input

{
  "headers": {
    "content-type": "application/json"
  },
  "body": {
    "hello": "world"
  },
  "query": "?",
  "parsed_query": {}
}

Transformation

addHandler("transform", (request, context) => {
  // assign the value to the new field
  request.body.new_hello = request.body.hello;

  // delete the previous field
  delete request.body.hello;

  // return the modified request
  return request;
});

Output

{
  "headers": {
    "content-type": "application/json",
    "content-length": "21"
  },
  "body": {
    "new_hello": "world"
  },
  "query": "?",
  "parsed_query": {}
}

Os produtores de webhooks controlam o formato em que o payload é enviado. Se o consumidor precisa da informação em outro formato, é necessário um processo de transformação antes que o consumidor receba o webhook.

Uma forma de conseguir isso é colocar um servidor proxy entre o provedor e o consumidor do webhook. O proxy faz o trabalho de converter o payload enviado pelo provedor em um formato com o qual o consumidor consiga trabalhar. Outra estratégia é usar funções de middleware para transformar os dados recebidos no endpoint do consumidor.

Você esqueceu a política específica de cada provedor

Problema

Você precisa centralizar as políticas.

Solução

O Hookdeck usa Rulesets para definir um comportamento padrão para todos os provedores que enviam webhooks para a sua API de destino. Toda connection no Hookdeck usa um ruleset padrão que pode ser ajustado com regras sobre retries de webhooks, rate limits e alertas.

Cada provedor de webhooks tem um conjunto diferente de regras para o tratamento dos webhooks. Diferenças em coisas como duração do timeout, retries, rate limiting e lógica de alertas levam a um fluxo de trabalho inconsistente quando você lida com webhooks de múltiplos provedores.

Para mitigar esse problema, você precisa usar um servidor proxy (como um API gateway) para harmonizar as operações de múltiplos provedores, alinhando-as a um conjunto uniforme de regras definido no proxy. Essas regras controlam como os webhooks interagem com o seu servidor de destino.

Você não sabe como as integrações anteriores foram configuradas

Problema

Você precisa entender a configuração num relance.

Solução

A página Connections permite ver o comportamento de cada webhook.

A configuração de webhooks varia de provedor para provedor, e esses provedores frequentemente mudam o processo de configuração. Isso torna a base de conhecimento sobre webhooks frágil e às vezes não transferível.

A forma recomendada de garantir um onboarding tranquilo e a transferência de conhecimento é documentar adequadamente o processo de configuração de cada provedor de webhooks.

Você recebe múltiplos webhooks para o mesmo evento

Problema

Você precisa tornar os seus endpoints de webhook idempotentes.

Quando provedores enviam a mesma requisição de webhook mais de uma vez, o efeito do webhook é duplicado dentro da aplicação. Isso coloca a aplicação em um estado inconsistente e reduz a integridade geral. Para mais sobre desafios de integridade de dados, veja como resolver problemas de integridade de dados com webhooks.

A solução é garantir que todos os endpoints que vão receber webhooks sejam idempotentes. Isso pode ser feito verificando IDs únicos de webhook para saber se um webhook já foi processado antes, ou escrevendo a lógica de processamento de forma idempotente. Você pode saber mais aqui.

Você implementa uma segurança diferente para cada provedor

Problema

Você precisa de uma interface centralizada para autenticar webhooks.

Solução

Com as Hookdeck Integrations, você precisa de apenas um fluxo de verificação para todos os seus webhooks. Você pode criar uma integração para qualquer provedor de webhooks que suporte Basic Auth, API keys ou HMAC, e as Hookdeck Integrations vão unificar automaticamente todos os métodos de autenticação de cada provedor em um único fluxo. Você também pode usar qualquer um dos templates de autenticação disponíveis para provedores populares como Shopify ou GitHub.

Provedores de webhooks oferecem diferentes tipos de métodos de autenticação. Ao trabalhar com múltiplos provedores, você precisa implementar e acompanhar cada estratégia de autenticação. Isso não é ideal, porque não escala com o tempo nem com o crescimento do número de provedores.

Resolver esse problema exige usar um proxy web, como um API Gateway, para abstrair os métodos de autenticação de cada provedor em um único fluxo de autenticação para o servidor de destino.

O provedor de webhooks só aceita uma URL de webhook

Problema

Você precisa fazer fan-out de um único webhook para múltiplos destinos.

Solução

As Hookdeck Connections dão a você a capacidade de pegar um único webhook e fazer fan-out da requisição para múltiplos destinos. Isso remove a limitação imposta pelo provedor quanto ao número de destinos.

Adicione um filtro para especificar os critérios sobre o body, header, query ou path dos eventos que serão entregues pela connection.

Quando um ou mais consumidores dependem de um webhook, você precisa comunicar a requisição a múltiplos destinos. Se o seu provedor de webhooks permite apenas um destino, é preciso criar uma forma de distribuir o webhook para vários destinos.

Sistemas de mensageria são usados para resolver esse tipo de problema. Uma fila ou um sistema pub/sub é colocado entre o provedor e o consumidor para desacoplar as duas entidades. Assim, múltiplos consumidores podem se inscrever no sistema de mensageria e cada um recebe uma cópia do webhook enviado pelo provedor.

O tempo de resposta do seu servidor está causando timeout nos webhooks

Problema

Você precisa responder aos webhooks dentro do limite de timeout.

Solução

Quando você configura connections do Hookdeck entre os seus provedores e os seus servidores consumidores, o Hookdeck age automaticamente como uma fila entre eles. O Hookdeck provisiona infraestrutura de alta disponibilidade para responder rapidamente aos provedores no mundo todo. Isso ajuda você a começar a processar os seus webhooks sem ter que gerenciar ou lidar com arquitetura orientada a eventos.

Quando um servidor excede o seu throughput, as requisições de webhook seguintes precisam esperar as ativas terminarem o processamento antes de serem processadas. Se esse tempo de espera ultrapassar o limite de resposta definido pelo provedor, os webhooks pendentes serão descartados.

A solução recomendada é processar os webhooks de forma assíncrona. Isso pode ser feito colocando um componente de fila entre o provedor de webhooks e o seu servidor, para desacoplar as duas entidades. Assim, todas as requisições de webhook recebem resposta quase imediatamente e ficam enfileiradas para o servidor consumir a um ritmo que não exceda o seu throughput.

Conclusão

Gerenciar webhooks em escala significa muito mais do que configurar um handler — significa lidar com estado de entrega, orçamentos de retry, segredos, observabilidade e um runbook para cada provedor que você integra. O que começa como um único handler de endpoint vira filas, workers de retry, ferramentas de observabilidade, verificação de assinatura e runbooks operacionais (antes mesmo de você entregar a funcionalidade que os webhooks deveriam suportar).

O Event Gateway do Hookdeck é uma infraestrutura de webhooks gerenciada que cuida de ingestão, entrega com backpressure, retries, observabilidade e verificação de assinatura prontos para uso. Ele fica entre os seus provedores de webhooks e a sua aplicação como uma fila gerenciada, absorvendo picos de tráfego, fazendo buffer das entregas e dando a você o trace completo de cada evento sem precisar operar nada disso.