O que são thin events?

Thin events são payloads de webhook que contêm o mínimo de informação, normalmente apenas um tipo de evento e um identificador de recurso, em vez do estado completo do recurso. São notificações de que algo mudou, sinalizando ao receptor que ele deve buscar os dados mais recentes na API do provedor.

Esse padrão só de notificação é cada vez mais reconhecido como uma boa prática para construir sistemas confiáveis baseados em webhooks, porque garante que você sempre trabalhe com os dados mais atuais, e não com um retrato possivelmente desatualizado.

Thin events vs. fat events

Na arquitetura orientada a eventos, existem duas abordagens principais para projetar payloads de webhook:

Fat events (event-carried state transfer)

Fat events incluem o estado completo de um recurso dentro do próprio payload do webhook. Quando você recebe o evento, já tem todas as informações necessárias para processá-lo sem fazer chamadas adicionais à API.

Vantagens:

• Acesso imediato aos dados, sem chamadas extras à API
• Menor uso da API e possível redução de custos
• É possível processar eventos mesmo se a API do provedor estiver temporariamente indisponível

Desvantagens:

• Os dados do payload podem estar desatualizados no momento em que você os processa
• Vulnerável a problemas de ordenação (um evento mais antigo processado depois de um mais novo pode corromper o seu estado)
• Payloads maiores, o que pode impactar transferência de rede e armazenamento
• Exige tratamento cuidadoso de eventos duplicados para manter a consistência dos dados

Thin events (padrão de notificação)

Thin events contêm apenas a informação essencial para identificar o que mudou, geralmente um tipo de evento e um ID de recurso, obrigando você a buscar o estado completo e atual na API.

Vantagens:

• Você sempre trabalha com os dados mais atualizados
• Lida naturalmente com eventos fora de ordem (a busca mais recente na API retorna o estado atual)
• Simplifica a lógica de idempotência (o processamento é baseado no estado real, não na sequência de eventos)
• Payloads menores

Desvantagens:

• Exige uma chamada adicional à API para cada evento
• Aumenta o uso da API, o que pode esbarrar em rate limits em escala
• Depende da disponibilidade da API do provedor

Como os thin events funcionam

O fluxo conceitual do padrão de thin event é direto:

sequenceDiagram
    participant ProviderAPI as API Provider
    participant YourSystem as Your System

    ProviderAPI->>YourSystem: Thin Event (Notification){ id: "res_123", type: "resource.updated" }
    YourSystem->>ProviderAPI: GET /resources/res_123
    ProviderAPI-->>YourSystem: Current Resource State
    YourSystem->>YourSystem: Process Latest Data

1. Receber a notificação: o seu sistema recebe um thin event indicando que um recurso mudou
2. Buscar o estado mais recente: antes de processar, você faz uma chamada à API para obter o estado atual do recurso
3. Processar os dados atuais: você processa o recurso usando os dados mais recentes da API, e não o payload do evento

Esse padrão garante que, mesmo que os eventos cheguem fora de ordem ou duplicados, o seu sistema sempre processe o estado mais atual do recurso.

Adoção no mercado

Embora o padrão de thin event já seja considerado há muito tempo uma boa prática no design de sistemas distribuídos, grandes provedores estão agora formalizando essa abordagem. A Stripe, um dos maiores provedores de webhooks, está adotando thin events como parte da evolução da sua API para ajudar desenvolvedores a construir integrações mais confiáveis.

Mas o padrão em si é universal e pode ser aplicado a webhooks de qualquer provedor. Mesmo que um provedor envie fat events, você pode optar por ignorar os dados do payload e buscar o recurso na API dele, tratando os eventos na prática como notificações thin.

Considerações de implementação

Embora os thin events tragam ganhos significativos de consistência de dados, eles introduzem desafios em escala, especialmente em relação a rate limits de API. Quando o seu sistema recebe um alto volume de webhooks em um curto intervalo, buscar o recurso a cada evento pode rapidamente estourar os rate limits da API do provedor.

Para orientações práticas de implementação de thin events em produção, incluindo tratamento de erros, lógica de retry e boas práticas operacionais, veja Boas práticas para trabalhar com thin events.

Para implementar thin events de forma eficaz evitando problemas de rate limit, veja o nosso guia sobre o padrão fetch before process em webhooks, que aborda estratégias para desacoplar ingestão e processamento usando queues e throttling.

Para um contexto mais amplo sobre padrões orientados a eventos e princípios de design, consulte Fundamentos de arquitetura orientada a eventos.

Como a Hookdeck ajuda

Adotar thin events resolve um problema de arquitetura (payloads inchados e dados desatualizados), mas não muda a infraestrutura de entrega que você ainda precisa ter: ingestão, retries, observabilidade e verificação em cada origem de eventos. O que começa como um único handler de endpoint vira queues, workers de retry, ferramentas de observabilidade, verificação de assinatura e runbooks operacionais (antes mesmo de você entregar a funcionalidade que os webhooks deveriam sustentar)

O Event Gateway da Hookdeck é uma infraestrutura de webhooks gerenciada que cuida de ingestão, entrega com backpressure, retries, observabilidade e verificação de assinatura por padrão. Ele fica entre os seus provedores de webhook e a sua aplicação como uma fila gerenciada, absorvendo picos de tráfego, fazendo buffer das entregas e dando a você o rastro completo de cada evento sem precisar operar nada disso. Comece a usar a Hookdeck e pule os meses de encanamento que uma infraestrutura de webhooks em produção normalmente exige.

Resumo

Thin events representam uma abordagem de webhooks só de notificação que prioriza a consistência dos dados em vez da conveniência. Ao tratar payloads de webhook como sinais, e não como fonte da verdade, você constrói sistemas resilientes a desafios comuns de sistemas orientados a eventos, como problemas de ordenação e duplicatas. Embora esse padrão exija uma implementação cuidadosa, principalmente na gestão de chamadas à API, ele oferece uma base sólida para integrações de webhook confiáveis e escaláveis.