logo
logo

Boas práticas no uso de webhooks

Siga estas recomendações ao trabalhar com webhooks.
Responda à request com 202 Accepted em até dois segundos. O tempo limite da request é de cinco segundos. Use uma fila para armazenar o evento e processe depois. Isso evita falhas por timeout e garante resiliência a grandes volumes.
Valide a assinatura usando o byte array do body, sem transformações. Não altere ou faça parse antes de validar. Use o buffer bruto da request para evitar inconsistências.
Pode haver atrasos na entrega de eventos. Se um evento antigo causa problemas, compare o timestamp do evento com a hora atual.
Você pode receber o mesmo evento mais de uma vez. Implemente operações idempotentes. Identifique duplicidades pelo campo id do evento.
Monitore códigos de resposta e métricas de entrega. Corrija falhas antes que impactem seus usuários.
Se sua aplicação ficar offline, recupere eventos das últimas 8h pelo endpoint de polling. Use polling com frequência menor como fallback, por exemplo, a cada 30 minutos.
Garanta que os IPs abaixo estejam liberados no firewall para receber requests dos webhooks:
  • 34.202.11.230
  • 34.228.183.194
  • 44.207.41.97
  • 44.208.105.236
  • 54.85.55.192
Podemos alterar esses IPs sem aviso prévio. Sempre consulte a documentação para obter a lista atualizada.
Para maior segurança, permita apenas os IPs necessários, evitando liberar todos os IPs externos.