EVENTOS DE PAGAMENTO
Webhooks de pagamento: confirmação, segurança e reprocessamento
Webhook de pagamento é uma notificação enviada ao servidor da empresa quando o estado de uma cobrança muda. Como a entrega acontece pela rede e pode repetir, atrasar ou chegar fora de ordem, o receptor precisa validar origem, responder rápido e processar de forma idempotente.
Receba e confirme rapidamente
Valide estrutura e assinatura, registre o evento e devolva a resposta esperada sem executar toda a regra na requisição. O processamento pesado deve seguir em fila para evitar timeout e repetição desnecessária.
Validação e proteção
Use HTTPS, segredo específico, comparação segura e controle de replay quando suportado. Não confie apenas no endereço IP e não registre dados sensíveis sem necessidade.
Duplicidade e ordem
Guarde o identificador do evento e o estado atual do objeto. Um evento antigo não deve reverter uma atualização nova. Repetição com o mesmo ID precisa produzir o mesmo resultado sem duplicar entrega ou receita.
Reprocessamento e auditoria
Mantenha fila de falhas, tentativas, motivo e ferramenta de reprocessamento. Compare eventos com consultas periódicas para encontrar lacunas.
Se você quer avaliar esse desenho na sua operação, fale com um especialista da Marcha. A recomendação final depende do modelo de negócio, do fluxo financeiro e da análise cadastral e comercial.
Recebimento e validação
Exponha endpoint HTTPS, valide assinatura e horário conforme o provedor e limite tamanho do corpo. Preserve o payload necessário para auditoria com acesso restrito. Não confie em parâmetros de URL ou em origem de rede como única autenticação.
Responda rapidamente após persistir o evento. Processamento pesado deve seguir em fila para evitar reenvios causados por timeout.
Eventos repetidos e fora de ordem
Use identificador do evento e da entidade para deduplicar. Aplique transições válidas, não apenas o último evento recebido. Um evento antigo não deve reverter um estado final sem regra explícita.
Quando faltar contexto, consulte a API e registre a reconciliação. Mantenha dead-letter queue e ferramenta segura para reprocessar após correção.
Monitoramento da entrega
Acompanhe recebidos, validados, duplicados, processados, falhos e idade da fila. Alertas devem indicar impacto, provedor e tipo de evento. Guarde correlação com pedido e tentativa.
Teste rotação de segredo, indisponibilidade, reenvio e payload inesperado. Um painel de saúde permite distinguir atraso do provedor de falha na aplicação.
Perguntas frequentes
Webhook pode chegar duas vezes?
Sim. O receptor deve ser idempotente.
Preciso responder antes de processar?
Em geral, registre e responda rápido; siga a documentação específica do provedor.
Posso confiar na ordem?
Não como regra geral. Compare versão, data e estado permitido antes de aplicar a transição.
O que fazer se perder um evento?
Use consulta de reconciliação e mecanismo de reenvio ou reprocessamento.
Quanto tempo devo guardar um webhook?
A retenção depende de necessidade operacional, contrato, segurança e regras aplicáveis. Guarde informação suficiente para reconciliar e auditar, minimizando dados pessoais e restringindo acesso. Documente prazo e descarte. Para investigação longa, preserve referências e evidências necessárias sem manter payload completo indefinidamente.
Como reprocessar um webhook com segurança?
Localize o evento original, confirme autenticidade e estado atual da entidade e use a mesma chave de deduplicação. Reexecute pelo consumidor normal, com registro de operador, motivo e resultado. Não edite o payload para forçar sucesso. Se o erro veio do código, publique a correção, teste com cópia autorizada e acompanhe efeitos dependentes antes de encerrar a ocorrência.