Melhores práticas

Este guia apresenta recomendações para garantir robustez, confiabilidade e segurança ao integrar com webhooks.

Responda rapidamente

• 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

Valide a assinatura usando os bytes brutos do corpo

• 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 == receivedSignature

Lide com atrasos e tentativas de nova entrega

• Os 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

Implemente idempotência

• 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)

Monitore e acompanhe falhas

• 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

Implemente rotinas de reconciliação

• 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

Configure a segurança de rede

• 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

Teste sua implementação

• 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