Este guia apresenta recomendações para garantir robustez, confiabilidade e segurança ao integrar com webhooks.
Retorne um 202 Accepted HTTP código de status em até 2 segundos após receber uma solicitação de webhook
Use filas de mensagens (como RabbitMQ, SQS ou Kafka) para processar eventos de forma assíncrona
Mantenha o processamento do endpoint do webhook leve para evitar timeouts
Considere implementar um processo worker separado para o tratamento de eventos complexos
Sempre verifique a assinatura do webhook antes de processar qualquer evento
Use o array de bytes bruto do corpo da solicitação sem nenhuma transformação
Evite parsing automático ou conversões de codificação de caracteres antes da validação
Armazene o segredo do seu webhook com segurança (use variáveis de ambiente ou um cofre seguro)
Exemplo de pseudocódigo para validação de assinatura:
calculatedSignature = HMAC-SHA256(webhookSecret, rawRequestBody)
return calculatedSignature == receivedSignatureOs eventos podem chegar atrasados devido a problemas de rede ou mecanismos de nova tentativa
Sempre verifique o timestamp do evento (time campo) para determinar a idade do evento
Implemente lógica para lidar adequadamente com eventos antigos conforme o seu caso de uso
Considere definir um limite máximo de idade para processar eventos
O mesmo evento pode ser recebido várias vezes devido a problemas de rede ou tentativas de nova entrega
Use o id campo como uma chave de idempotência para detectar e ignorar duplicatas
Armazene os IDs dos eventos processados em um banco de dados persistente com TTL apropriado
Torne sua lógica de processamento de eventos idempotente (segura para executar várias vezes)
Implemente logging abrangente para todos os eventos de webhook
Monitore métricas de entrega, códigos de resposta e tempos de processamento
Configure alertas para falhas recorrentes ou padrões incomuns
Mantenha uma fila de erros dedicada para tentativas de processamento de webhook com falha
Implemente um dashboard para visualizar métricas de saúde do webhook
Se sua aplicação ficar indisponível, você pode perder eventos
Implemente rotinas de polling para buscar eventos perdidos durante períodos de indisponibilidade
Agende verificações regulares de consistência entre o seu sistema e a nossa API
Considere implementar uma dead letter queue para eventos que falharem no processamento várias vezes
Permita os seguintes IPs do serviço de webhook no seu firewall:
34.234.120.59
18.229.212.133
3.218.90.124
44.219.96.170
18.235.54.162
Certifique-se de que sua configuração de SSL/TLS esteja atualizada
Considere usar um serviço de proxy de webhook para segurança adicional
Implemente limitação de taxa nos seus endpoints de webhook para evitar abuso
Use nossas ferramentas de teste de webhook para verificar sua integração
Implemente um ambiente de desenvolvimento que possa receber webhooks de teste
Crie testes automatizados para verificar sua lógica de tratamento de webhook
Revise e atualize regularmente sua integração de webhook
Atualizado