Webhooks na Prática

const maxBodyBytes int64 = 1024

if r.Method != http.MethodPost { // Recuse antes de ler o corpo.
	http.Error(w, "método inválido", http.StatusMethodNotAllowed)
	return
}
body, err := io.ReadAll(io.LimitReader(r.Body, maxBodyBytes+1))
if err != nil || int64(len(body)) > maxBodyBytes { // Detecte o byte excedente.
	http.Error(w, "corpo inválido", http.StatusRequestEntityTooLarge)
	return
}
w.WriteHeader(http.StatusAccepted) // Confirme só depois das guardas.

Pense na doca de um depósito. O caminhão não entra direto na área de estoque: primeiro a portaria confirma a doca, confere o manifesto e pesa a carga. Um endpoint de webhook é essa portaria. Ele recebe uma requisição criada por outro sistema, não por uma tela sob seu controle. Por isso, método, tamanho, headers e resposta fazem parte da segurança e da operação, não são acabamento.

Se você chamar io.ReadAll sem limite, um cliente pode consumir memória proporcional ao corpo. Se decodificar JSON antes de preservar os bytes, a assinatura da próxima aula poderá ser calculada sobre uma representação diferente. Se devolver 500 depois de aceitar o evento, o provedor tentará novamente e poderá repetir um efeito. A entrada precisa ter um funil explícito.

O handler aceita somente POST, envolve r.Body com http.MaxBytesReader ou io.LimitReader, lê uma única vez e guarda []byte. Depois valida os metadados mínimos. Nesta aula o processamento termina em uma confirmação; nas próximas, os mesmos bytes passam por autenticação e idempotência. Um 202 Accepted comunica que a entrega foi recebida para processamento, enquanto 204 No Content serve quando o trabalho já terminou sem resposta.

Esse fluxo também define responsabilidade operacional. O provedor considera qualquer resposta fora da faixa de sucesso como motivo potencial para nova tentativa. Portanto, o status HTTP não é um detalhe cosmético: ele controla a fila do outro lado. Responda rapidamente, registre um identificador correlacionável e mova trabalho demorado para uma etapa que você consegue observar. Nunca registre segredo, assinatura completa ou payload sensível apenas para facilitar debug.

A fronteira deve permanecer determinística nos testes. httptest, readers em memória, relógio injetado e fixtures gravadas reproduzem os casos sem abrir porta, esperar timer ou depender de serviço externo. Isso torna falhas repetíveis e permite demonstrar o receiver em uma revisão de código ou entrevista técnica.

Há ainda um contrato de manutenção: cada etapa deve produzir evidência suficiente para diagnosticar uma recusa sem reproduzir dados confidenciais. Conte status por provedor, classifique falhas de formato, assinatura e duplicidade e preserve um ID de correlação. Uma métrica agregada responde se o problema começou após deploy ou rotação de segredo; o ID permite localizar uma entrega específica. O corpo completo raramente precisa aparecer no log. Essa escolha reduz exposição e mantém a investigação útil.