O que é um Webhook? Eventos, Entrega, Segurança e Design

A API de Scraping sem Raspagem pode enviar uma solicitação HTTP POST para uma URL de webhook configurada quando uma tarefa de scraping assíncrona é concluída.

O que é um Webhook?

Um webhook é um mecanismo pelo qual um sistema envia uma solicitação HTTP para outro sistema após um evento. O aplicativo receptor registra uma URL de endpoint e frequentemente escolhe tipos de eventos como tarefa concluída, fatura paga, registro atualizado, implantação finalizada ou mensagem entregue. Quando o evento ocorre, o produtor chama esse endpoint com os dados e metadados do evento.

Um webhook é às vezes descrito como uma chamada API reversa. Em uma interação API comum, o consumidor inicia uma solicitação para ler ou mudar o estado. Com um webhook, o produtor inicia uma solicitação para notificar o consumidor. A URL receptora ainda é um endpoint HTTP, e a implementação deve aplicar práticas comuns de segurança, validação, disponibilidade e observabilidade da API.

O Especificação de Webhooks Padrão coleta convenções para entrega de webhook segura e interoperável. Ela cobre payloads, metadados de eventos, assinaturas e comportamento operacional, enquanto provedores individuais ainda definem seus próprios tipos de eventos e contratos.

Como um Webhook Funciona

1. O consumidor registra um endpoint. O registro pode ocorrer em um dashboard ou API e geralmente associa um segredo à assinatura.
2. O consumidor seleciona eventos. Assinaturas restritas reduzem o tráfego e a exposição de dados desnecessários.
3. O produtor registra um evento. Uma ação de domínio cria um evento ou tarefa de entrega imutável com um identificador estável.
4. O produtor constrói o payload. Ele serializa um tipo de evento, ID de evento, hora de ocorrência, versão de esquema e dados relevantes.
5. O produtor assina a entrega. A assinatura cobre o corpo bruto e os metadados de frescor sob o esquema documentado.
6. O produtor envia uma solicitação HTTP. POST com um corpo JSON é comum, mas o contrato determina o método e o tipo de mídia.
7. O consumidor verifica e registra. O endpoint verifica transporte, assinatura, timestamp, ID de evento, esquema e assinatura antes de aceitar o evento.
8. O consumidor reconhece. Ele retorna o status de sucesso documentado após aceitação durável e realiza processamento mais longo através de uma fila ou trabalhador.

Exemplo de Payload de Webhook

Um pequeno envelope de evento pode separar metadados de dados de domínio:

{
  "id": "evt_7f32",
  "type": "task.completed",
  "occurred_at": "2026-08-24T03:10:00Z",
  "version": "1",
  "data": {
    "task_id": "task_b18c",
    "status": "completed"
  }
}

A data mostrada é uma constante de código ilustrativa em vez de um carimbo de publicação. O ID do evento suporta deduplicação, o tipo seleciona o manipulador e esquema, a hora de ocorrência descreve o evento de domínio e a versão controla a evolução do payload. O tempo de entrega pertence aos metadados da solicitação quando o esquema de assinatura o utiliza.

Não assuma que o corpo de um webhook contém o recurso completo atual. Alguns produtores enviam uma notificação simples com um ID, após o qual o consumidor chama a API para buscar o estado atual autorizado. Outros enviam uma captura de evento completa. O contrato deve informar se o payload representa o evento, o recurso após o evento ou um ponteiro.

Webhooks vs Polling, APIs e WebSockets

Sistemas importantes muitas vezes combinam padrões. Um webhook fornece notificação rápida, enquanto um processo de reconciliação programada compara o estado atual da API com o estado local. O webhook melhora a latência; a reconciliação detecta lacunas ou alterações de política sem assumir que um caminho de entrega é perfeito.

Como Funcionam as Assinaturas de Webhook

Um design de segredo compartilhado comumente utiliza um hash com chave sobre o corpo da solicitação bruta exato mais metadados, como um timestamp de entrega e um ID de evento. HMAC é uma construção padrão para autenticação de mensagens, definida em RFC 2104Outros provedores usam assinaturas assimétricas para que os consumidores possam verificar com uma chave pública.

O consumidor deve seguir o algoritmo byte a byte do provedor. Analise o cabeçalho da assinatura de acordo com seu formato versionado, reconstrua o conteúdo assinado exatamente, calcule o valor esperado e compare através de uma função de tempo constante. Apenas após a verificação, o código deve analisar e confiar na carga JSON.

O middleware do framework pode interromper a verificação quando analisa JSON e o serializa novamente. O espaço em branco, a ordem das propriedades, a escape e a formatação de números podem mudar mesmo que os dados pareçam equivalentes. Capture os bytes do corpo bruto antes da análise comum do corpo e, em seguida, passe os bytes verificados para o analisador JSON.

Proteção contra Repetição e Idempotência

Um webhook antigo válido pode ser reproduzido maliciosamente se a assinatura nunca expirar. Portanto, os esquemas de assinatura incluem um carimbo de data/hora de entrega ou outro valor de frescor. O receptor aceita apenas uma pequena janela de tempo documentada e deve manter seu relógio sincronizado. A verificação do carimbo de data/hora complementa, em vez de substituir, a deduplicação do ID do evento.

Idempotência significa que processar o mesmo evento lógico mais de uma vez produz o mesmo resultado comercial que processá-lo uma vez. Armazene o ID de evento estável do produtor em uma tabela com uma restrição de exclusividade, idealmente na mesma transação que aplica a mudança comercial. Marcar um evento como "visto" antes da atualização comercial pode resultar em perda de trabalho se o processo parar entre essas ações.

Algumas operações são naturalmente idempotentes, como definir o status de um registro para uma versão específica. Outras, como aumentar um saldo ou enviar uma mensagem, precisam de um registro de idempotência vinculado ao ID do evento. Deduplique pelo identificador documentado do produtor, não pela hash do payload, porque dois eventos legítimos podem ter corpos idênticos.

Pedidos e Versões de Evento

A ordem de entrega pode diferir da ordem de ocorrência porque os eventos podem passar por trabalhadores, regiões ou filas separadas. Uma atualização mais recente pode chegar antes de uma mais antiga. Os consumidores não devem tratar a ordem de chegada como ordem de negócios, a menos que o produtor a garanta explicitamente para a assinatura.

Inclua uma versão de recurso, sequência ou tempo de ocorrência de evento com semânticas definidas. Aplique uma atualização de estado somente quando sua versão for mais nova do que a versão local. Para eventos que representam ações imutáveis em vez de instantâneos de estado, preserve as regras de sequência de eventos estabelecidas pelo domínio.

A versão do esquema é separada da versão do recurso. A versão do esquema descreve a forma do payload; a versão do recurso descreve o estado de uma entidade particular. Manter os conceitos distintos impede que uma mudança no formato do payload pareça um novo registro comercial.

Reconhecer Primeiro, Processar Através de uma Fila

Um endpoint de webhook deve realizar um trabalho limitado: impor o tamanho da solicitação, verificar a assinatura, validar o envelope, reservar o ID do evento, armazenar ou adicionar à fila o evento aceito e retornar a resposta de sucesso documentada. Junções lentas de banco de dados, chamadas de API externas, geração de arquivos e envio de emails pertencem a trabalhadores.

A aceitação durável é importante. Retornar sucesso antes que o evento seja registrado pode perdê-lo se o processo parar. Esperar por cada ação a montante antes de responder faz com que o produtor mantenha uma conexão e pode causar entregas repetidas quando o endpoint excede seu prazo de resposta.

A mensagem da fila deve conter o evento verificado, o contexto da assinatura e identificadores de rastreamento seguros. Segredos usados para verificação de assinatura não pertencem à carga útil da fila.

Segurança do Registro de Endpoint

Se os usuários puderem registrar URLs de webhook arbitrárias, o produtor se torna um cliente HTTP agindo com base na entrada do usuário. O sistema deve se proteger contra falsificação de requisições do lado do servidor. O Folha de Dicas para Prevenção de SSRF da OWASP descreve controles de lista permitida e de camada de rede.

Exija HTTPS para endpoints públicos, resolva e valide destinos, bloqueie loopback, link-local, ranges privados, de metadados e de serviço interno, e aplique as verificações novamente após redirecionamentos e resolução de DNS de acordo com a política escolhida. Limite portas, métodos, bytes de resposta, tempo de conexão e comportamento de redirecionamento.

Verifique a propriedade do endpoint durante o registro por meio de um desafio ou handshake assinado. Trate os corpos de resposta do webhook como não confiáveis e não exponha detalhes internos da rede através de mensagens de erro de entrega.

Casos Comuns de Uso de Webhook

Observabilidade e Operações

Rastreie ID de evento, ID de assinatura, tipo de evento, versão do esquema, hora recebida, decisão de verificação, status de reconhecimento, estado de processamento e identificadores de correlação seguros. Não registre segredos de assinatura, cabeçalhos de autorização completos ou campos de carga útil sensíveis.

Meça latência de aceitação, atraso na fila, duração de processamento, taxa de duplicatas, falhas de assinatura, esquemas inválidos, carimbos de data/hora obsoletos e conflitos de ordenação. Separe a saúde de entrega do produtor da saúde de processamento empresarial do consumidor para que um evento aceito que falhe depois não desapareça em uma métrica geral de sucesso.

Forneça uma visão administrativa controlada que possa pesquisar por ID de evento e mostrar o histórico de entrega redigido. As equipes de operações precisam de evidências suficientes para diagnosticar uma mudança de estado ausente sem expor as credenciais ou o corpo sensível completo.

Lista de Verificação do Design de Webhook

1. Defina tipos e IDs de eventos estáveis. Documente se as cargas úteis são eventos, instantâneas ou ponteiros.
2. Versione o esquema. Declare regras de compatibilidade para novos campos opcionais e revisões de eventos.
3. Assine bytes brutos e metadados de frescor. Publique etapas exatas de verificação e suporte à substituição de segredos.
4. Imponha segurança no endpoint. Verifique a propriedade e bloqueie destinos SSRF.
5. Aceite de forma idempotente. Use um ID de evento exclusivo e um registro de deduplicação transacionalmente seguro.
6. Reconheça após aceitação durável. Mova trabalhos mais longos para uma fila.
7. Espere repetição e reordenação. Use versões de recurso e reconciliação em vez de suposições sobre a ordem de chegada.
8. Redija dados de observabilidade. Mantenha segredos e campos de carga útil sensíveis fora de logs e ferramentas de suporte.

Conclusão

Um webhook transforma um evento em uma notificação HTTP, fornecendo atualizações de baixa latência de integrações sem polling constante. A chamada HTTP é a parte fácil. Um design de produção verifica assinaturas de corpos brutos, impõe frescor, deduplica por ID de evento, lida com reordenação, reconhece somente após aceitação durável, processa através de uma fila, protege o registro de endpoint contra SSRF e reconcilia estados importantes. Esses controles transformam um callback em uma fronteira de integração confiável.