responda rápido
nunca processe tudo dentro da requisição. responda 2XX imediatamente e processe em background.
o timeout por tentativa é de 10 segundos. para processamentos mais lentos, use filas (SQS, RabbitMQ, etc).
trate idempotência
retries automáticos podem entregar o mesmo evento mais de uma vez. use eventId como chave única para evitar processamento duplicado.
valide a assinatura
configure um signing secret e valide cada requisição. sem validação, qualquer um pode enviar POSTs para sua URL.
veja como implementar em assinando requisições.
retorne o código HTTP correto
nunca retorne 200 para esconder um erro — isso faz o evento sumir silenciosamente.
registre logs
guarde logs de cada webhook recebido: eventId, eventType, timestamp e resultado do processamento. quando algo der errado, os logs são o único ponto de diagnóstico.
monitore
acompanhe taxa de sucesso e eventos com falha no painel em integrações > webhooks. veja monitoramento.