O que é um webhook e por que está em toda parte

Publicado em 2026-09-12 por frfrand

En lugar de preguntar cada cinco minutos, el otro servicio te avisa. Cómo funciona, por qué siempre hay que verificar la firma, y los tres detalles que rompen integraciones en producción.

Sem webhooks, a única forma de ficar sabendo de algo que acontece em outro serviço é perguntar: a cada minuto, a cada cinco, a cada hora. Isso se chama polling e tem dois problemas óbvios: você gasta chamadas para ouvir "não aconteceu nada", e fica sabendo tarde.

Um webhook inverte a direção. Você registra um endereço seu, e quando algo acontece, o outro serviço envia uma requisição HTTP.

É a mesma coisa que deixar seu telefone em vez de ligar a cada meia hora para perguntar se há novidades.

Como se vê na prática

Você registra uma URL. Quando ocorre o evento, chega algo assim:

POST /webhooks/pagos HTTP/1.1 X-Signature: sha256=8f3a... Content-Type: application/json

{"evento":"pago.aprobado","id":"pay_123","monto":4500}

Seu servidor recebe isso, verifica se é legítimo, faz o que for necessário e responde 200.

Verificar a assinatura não é opcional

Esse endereço é público: qualquer um que o conheça pode enviar dados. Sem verificação, qualquer um poderia dizer ao seu sistema "este pagamento foi aprovado".

Por isso, serviços sérios assinam cada envio com um segredo compartilhado. Seu trabalho é recalcular essa assinatura sobre o corpo recebido e compará-la.

Três detalhes que são esquecidos:

• É preciso assinar sobre o corpo bruto, não sobre o JSON já analisado e resserializado. Um espaço de diferença e a assinatura não coincide.
• A comparação deve ser de tempo constante, não um simples igual, para não vazar informações pelo tempo de resposta.
• Muitos serviços incluem uma marca de tempo: convém rejeitar envios antigos, para que ninguém possa reenviar um capturado.

Os três detalhes que quebram integrações

1. Responder rápido. Quem envia espera alguns segundos e, se não responder, considera que falhou e tenta novamente. Se seu manipulador levar trinta segundos para processar, você receberá o mesmo evento várias vezes.

A forma correta: validar, salvar o evento em uma fila, responder 200 e processar depois. O webhook confirma o recebimento, não o trabalho.

2. Os eventos se repetem. Por tentativas, por falhas de rede, por reenvio manual. Seu manipulador tem que ser idempotente: receber duas vezes "pagamento aprovado" não pode cobrar duas vezes.

A forma habitual é salvar o identificador do evento e descartar os repetidos.

3. A ordem não é garantida. Você pode receber "pedido atualizado" antes de "pedido criado". Se sua lógica assumir sequência, vai falhar de formas estranhas e intermitentes. Quando a ordem importa, é preciso apoiar-se em marcas de tempo ou no estado atual, não na ordem de chegada.

Como são testados

O problema clássico: o serviço precisa de um endereço público e você está desenvolvendo na sua máquina.

Dois caminhos: um túnel que publique sua porta local temporariamente, ou guardar os eventos que chegam a um ambiente de testes e reproduzi-los localmente. O segundo é mais chato e muito mais confiável para depurar.

E o conselho que mais tempo economiza: quase todos os serviços guardam o histórico de entregas com o corpo enviado, o código de resposta e a resposta. Antes de mexer no código, dê uma olhada nesse histórico. Metade das vezes o problema está ali à vista: um 404 por uma rota mal escrita, ou um 500 que diz exatamente o que falhou.

Onde aparecem

Quase em todos os lugares: GitHub quando você faz push, plataformas de pagamento quando um cobrança é aprovada, WhatsApp quando chega uma mensagem, formulários quando alguém os envia.

No ArduMaker é o mecanismo que dispara as implantações: o GitHub avisa, o servidor valida a assinatura e executa a construção.