Enviando e recebendo webhooks na AWS: inove com notificações de eventos

Se você está criando um aplicativo de software como serviço (SaaS) que se integra aos fluxos de trabalho de seus clientes ou notificações de transações de um fornecedor, os webhooks desempenham um papel fundamental para desbloquear a inovação, aprimorar a experiência do usuário e simplificar as operações.

Este post explica como criar com webhooks na AWS e aborda dois cenários:

• Provedor de webhooks: um aplicativo SaaS que envia webhooks para uma API externa.
• Consumidor de webhooks: uma API que recebe webhooks com capacidade para lidar com grandes cargas úteis (payloads).

Ele inclui arquiteturas de referência de alto nível com considerações, melhores práticas e exemplos de código para orientar sua implementação.

Enviando webhooks

Para enviar webhooks, você gera eventos e os entrega para APIs de terceiros. Esses eventos facilitam atualizações, fluxos de trabalho e ações no sistema de terceiros. Por exemplo, uma plataforma de pagamentos (provedor) pode enviar notificações sobre status de pagamento, permitindo que lojas de comércio eletrônico (consumidores) enviem mercadorias após a confirmação.

Arquitetura de referência da AWS para um provedor de webhook

A arquitetura consiste em dois serviços:

• Entrega de webhook: um aplicativo que entrega webhooks a um endpoint externo especificado pelo consumidor.
• Gerenciamento de assinaturas: uma API de gerenciamento que permite ao consumidor gerenciar sua configuração, incluindo a especificação de endpoints para entrega e quais eventos devem ser assinados.

Considerações e melhores práticas para enviar webhooks

Ao criar um aplicativo para enviar webhooks, considere os seguintes fatores:

Geração de eventos: considere como você gera eventos. Este exemplo usa o Amazon DynamoDB como fonte de dados. Os eventos são gerados pela captura de dados de alterações para o DynamoDB Streams e enviados para o Amazon EventBridge Pipes. Em seguida, você simplifica o formato de resposta do DynamoDB usando um transformador de entrada.

Com o EventBridge, você envia eventos quase em tempo real. Se os eventos não forem urgentes, você poderá enviar vários eventos em um lote. Isso pode ser feito pesquisando novos eventos em uma frequência especificada usando o EventBridge Scheduler. Para gerar eventos de outras fontes de dados, considere abordagens semelhantes com as notificações de eventos do Amazon Simple Storage Service (S3) ou o Amazon Kinesis.

Filtragem: o EventBridge Pipes suporta a filtragem por meio da correspondência de padrões de eventos, antes que o evento seja roteado para o destino de destino. Por exemplo, você pode filtrar eventos relacionados às operações de atualização de status na tabela de pagamentos do DynamoDB para o endpoint relevante da API do assinante.

Entrega: os destinos de API do EventBridge entregam eventos fora da AWS usando chamadas de API REST. Para proteger o endpoint externo contra picos de tráfego, você define um limite de taxa de invocação. Além disso, as novas tentativas com recuo exponencial são tratadas automaticamente, dependendo do erro. Uma fila de mensagens mortas do Amazon Simple Queue Service (SQS) retém mensagens que não podem ser entregues. Eles podem fornecer uma entrega escalável e resiliente.

Estrutura da carga útil: considere como os consumidores processam as cargas de eventos. Este exemplo usa um transformador de entrada para criar uma carga estruturada, alinhada à especificação do CloudEvents. O CloudEvents fornece um formato padrão do setor e uma estrutura de carga útil comum, com ferramentas de desenvolvedor e SDKs para consumidores.

Tamanho da carga útil: Para uma entrega rápida e confiável, mantenha o tamanho da carga útil no mínimo. Considere fornecer somente os detalhes necessários, como identificadores e status. Para obter informações adicionais, você pode fornecer aos consumidores uma API separada. Os consumidores podem então chamar essa API separadamente para recuperar as informações adicionais.

Segurança e autorização: para entregar eventos com segurança, você estabelece uma conexão usando um método de autorização, como o OAuth. Nos bastidores, a conexão armazena as credenciais no AWS Secrets Manager, que criptografa com segurança as credenciais.

Gerenciamento de assinaturas: considere como os consumidores podem gerenciar suas assinaturas, como especificar endpoints HTTPS e tipos de eventos para assinar. O DynamoDB armazena essa configuração. O Amazon API Gateway, o Amazon Cognito e o AWS Lambda fornecem uma API de gerenciamento para operações.

Custos: na prática, o envio de webhooks gera custos, que podem se tornar significativos à medida que você cresce e gera mais eventos. Considere implementar políticas de uso, cotas e permitir que os consumidores se inscrevam somente nos tipos de eventos de que precisam.

Monetização: considere cobrar dos consumidores com base no volume ou nível de uso. Por exemplo, você pode oferecer um nível gratuito para fornecer um acesso de baixo atrito aos webhooks, mas somente até um determinado volume. Para obter volume adicional, você cobra uma taxa de uso alinhada ao valor comercial que seus webhooks fornecem. Em grandes volumes, você oferece um nível premium em que fornece infraestrutura dedicada para determinados consumidores.

Monitoramento e solução de problemas: além da arquitetura, considere os processos para as operações diárias. Como os endpoints são gerenciados por terceiros, considere habilitar o autoatendimento. Por exemplo, permita que os consumidores visualizem status, reproduzam eventos e pesquisem registros de webhook anteriores para diagnosticar problemas.

Cenários avançados: este exemplo foi desenvolvido para casos de uso populares. Para cenários avançados, considere serviços alternativos de integração de aplicativos observando suas cotas de serviço. Por exemplo, o Amazon Simple Notification Service (SNS) para distribuição a um número maior de consumidores, o Lambda pela flexibilidade de personalizar cargas e autenticação e o AWS Step Functions para orquestrar um padrão de disjuntor  (circuit breaker) para desativar assinantes não confiáveis.

Recebendo webhooks

Para receber webhooks, você precisa de uma API para fornecer ao provedor de webhooks. Por exemplo, uma loja de comércio eletrônico (consumidor) pode confiar nas notificações fornecidas por sua plataforma de pagamento (provedor) para garantir que as mercadorias sejam enviadas em tempo hábil. Os webhooks apresentam um cenário único, pois o consumidor deve ser escalável, resiliente e garantir que todas as solicitações sejam recebidas.

Arquitetura de referência da AWS para um consumidor de webhook

Nesse cenário, considere um caso de uso avançado que possa lidar com grandes cargas usando o padrão de verificação de declaração.

Em um alto nível, a arquitetura consiste em:

• API: um endpoint de API para receber webhooks. Um sistema orientado por eventos então autoriza e processa os webhooks recebidos.
• Armazenamento de carga útil: o S3 fornece armazenamento escalável para cargas úteis grandes.
• Processamento de webhook: o EventBridge Pipes fornece uma arquitetura extensível para processamento. Ele pode agrupar, filtrar, enriquecer e enviar eventos para uma variedade de serviços de processamento como alvos.

Considerações e melhores práticas para receber webhooks

Ao criar um aplicativo para receber webhooks, considere os seguintes fatores:

Escalabilidade: os provedores normalmente enviam eventos à medida que eles ocorrem. O API Gateway fornece um endpoint gerenciado escalável para receber eventos. Se indisponíveis ou limitados, os provedores podem repetir a solicitação, mas isso não é garantido. Portanto, é importante configurar limites apropriados de taxa e de intermitência. A limitação das solicitações no ponto de entrada reduz o impacto nos serviços downstream, onde cada serviço tem suas próprias cotas e limites. Em muitos casos, os fornecedores também estão cientes do impacto nos sistemas downstream. Dessa forma, eles enviam eventos com um limite de taxa, normalmente de até 500 transações por segundo (TPS).

Além disso, o API Gateway permite validar solicitações, monitorar erros e se proteger contra negação de serviço distribuída (DDoS). Isso inclui ataques de camada 7 e camada 3, que são ameaças comuns aos consumidores de webhook devido à exposição pública.

Autorização e verificação: os provedores podem oferecer suporte a diferentes métodos de autorização. Considere um cenário comum com o Código de Autenticação de Mensagens (HMAC) baseado em hash, em que um segredo compartilhado é estabelecido e armazenado no Secrets Manager. Em seguida, uma função do Lambda verifica a integridade da mensagem, processando uma assinatura no cabeçalho da solicitação. Normalmente, a assinatura contém um carimbo (timestemp) de data e hora com uma expiração para mitigar ataques de repetição, em que os eventos são enviados várias vezes por um invasor. Como alternativa, se o provedor oferecer suporte ao OAuth, considere proteger a API com o Amazon Cognito.

Tamanho da carga útil: os provedores podem enviar uma variedade de tamanhos de carga útil. Os eventos podem ser agrupados em lotes para uma única solicitação maior ou podem conter informações significativas. Considere os limites de tamanho da carga útil em seu sistema orientado por eventos. O API Gateway e o Lambda têm limites de 10 Mb e 6 Mb. No entanto, o DynamoDB e o SQS estão limitados a 400 kb e 256 kb (com extensão para mensagens grandes), o que pode representar um gargalo.

Em vez de processar toda a carga, o S3 armazena a carga útil. Em seguida, ele é referenciado no DynamoDB, por meio do nome do bucket e da chave do objeto. Isso é conhecido como padrão de verificação de reivindicação. Com essa abordagem, a arquitetura suporta cargas de até 6 MB, de acordo com a cota de carga útil de invocação do Lambda.

Idempotência: Para maior confiabilidade, muitos fornecedores priorizam a entrega pelo menos uma vez, mesmo que isso signifique não garantir exatamente uma entrega. Eles podem transmitir a mesma solicitação várias vezes, resultando em duplicatas. Para lidar com isso, uma função do Lambda compara o identificador exclusivo do evento em relação aos registros anteriores no DynamoDB. Se ainda não tiver sido processado, você cria um item do DynamoDB.

Pedido: considere processar as solicitações na ordem pretendida. Como a maioria dos fornecedores prioriza a entrega pelo menos uma vez, os eventos podem estar fora de ordem. Para indicar a ordem, os eventos podem incluir um carimbo de data/hora ou um identificador de sequência na carga útil. Caso contrário, o pedido pode ser feito da melhor maneira possível, com base em quando o webhook é recebido. Para lidar com os pedidos de forma confiável, selecione serviços orientados a eventos que garantam o pedido. Este exemplo usa o DynamoDB Streams e o EventBridge Pipes.

Processamento flexível: o EventBridge Pipes fornece integrações a uma variedade de serviços orientados a eventos como alvos (target). Você pode rotear eventos para alvos diferentes com base em filtros. Diferentes tipos de eventos podem exigir processadores diferentes. Por exemplo, você pode usar o Step Functions para orquestrar fluxos de trabalho complexos, o Lambda para operações computacionais com menos de 15 minutos de tempo de execução, o SQS para armazenar solicitações em buffer e o Amazon Elastic Container Service (ECS) para trabalhos computacionais de longa duração. Os EventBridge Pipes fornecem transformação para garantir que somente as cargas úteis necessárias sejam enviadas e enriquecimento se forem necessárias informações adicionais.

Custos: este exemplo considera um caso de uso que pode lidar com grandes cargas úteis. No entanto, se você puder garantir que os provedores enviem cargas úteis mínimas, considere uma arquitetura mais simples sem o padrão de verificação de solicitações para minimizar os custos.

Conclusão

Os webhooks são um método popular para aplicativos se comunicarem e para empresas colaborarem e se integrarem com clientes e parceiros.

Esta postagem mostra como você pode criar aplicativos para enviar e receber webhooks na AWS. Ele usa serviços Serverless, como EventBridge e Lambda, que são adequados para casos de uso orientados a eventos. Ele abrange arquiteturas de referência de alto nível, considerações, melhores práticas e exemplos de código para ajudar na criação de sua solução.

Para conhecer os padrões e as melhores práticas sobre webhooks, visite os recursos da comunidade de código aberto Webhooks.fyi e CloudEvents.io.

Para obter mais recursos de aprendizado Serverless, visite Serverless Land.