Como tratar callbacks duplicados e novas tentativas de API
Uma API pode enviar uma operação, perder a resposta por timeout e tentar novamente sem saber se a primeira solicitação foi concluída. Um agregador de jogos ou uma fila de mensagens também pode reenviar o mesmo callback. Se cada entrega for interpretada como nova aposta, prêmio, estorno ou bonificação, a plataforma de cassino acumulará diferenças financeiras. Por isso, é necessário separar a tentativa de entrega da transação de negócio e garantir que o efeito monetário seja registrado apenas uma vez no livro-razão da operadora. Provedores utilizam identificadores, códigos de duplicidade e políticas de repetição diferentes: não existe uma resposta universal. O artigo apresenta validação do remetente, registros atômicos, respostas seguras, tratamento de mensagens fora de ordem, conciliação e testes. [1] [2] [4]
Publicado em
A entrega pode se repetir; o efeito financeiro deve ser único.
Neste artigo
Por que o mesmo callback pode chegar várias vezes?
O remetente pode não receber a resposta HTTP mesmo depois de o destino concluir a operação. Ele tenta novamente, ou uma fila reentrega uma mensagem cujo reconhecimento não foi registrado. A entrega pelo menos uma vez admite duplicatas, e a ordenação normalmente não é garantida. Receber duas vezes não significa necessariamente fraude ou uma segunda transação de negócio. [4] [5]
No cassino, um débito, crédito ou estorno não pode ser lançado duas vezes só porque o callback voltou. O efeito na carteira, o recebimento do evento e a resposta HTTP possuem ciclos distintos. St8 e 7SoftTech identificam repetições por IDs de transação, mas divergem em respostas e casos especiais. [1] [2]
Quais identificadores formam a chave de idempotência?
Diferencie ID da entrega, provedor autenticado, transação de negócio, tipo de operação, lançamento original referenciado e rodada de jogo. O controle contra lançamentos duplicados deve usar a identidade de negócio definida pelo contrato. Verifique o escopo de unicidade: sistemas de provedores e operadoras diferentes podem gerar o mesmo identificador textual. [1] [2] [3]
Identificador
Finalidade
Regra
Provedor / operador
Definir namespace
Validar origem autorizada
ID da transação
Identificar movimento
Único no escopo contratual
Tipo de operação
Débito, crédito, reversão
Seguir modelo de API
ID do evento
Marcar uma entrega
Nem sempre é a chave da carteira
ID do lançamento original
Vincular estorno
Conferir referência
Rodada e jogador
Contexto da operação
Não substituem o ID de transação
Armazene a impressão digital dos parâmetros e o estado junto à chave. Se o mesmo ID vier com outro valor, moeda ou jogador, existe conflito; não é licença para processar de novo. A AWS descreve a preservação da intenção original para APIs que admitem repetição segura. [3] [4]
O que validar antes de identificar uma duplicata?
Antes de consultar a chave, valide assinatura ou autenticação exigida pelo provedor sobre o conteúdo correto da mensagem. Depois, autorize origem, operador, jogador, carteira, moeda, ação e sessão quando aplicável. Um ID já conhecido, enviado por uma fonte falsa, não comprova que o movimento foi executado. A OWASP recomenda confirmar a autenticidade de webhooks antes de tratar repetições. [1] [6]
Verificar assinatura, prazo e defesa contra replay segundo o protocolo específico do provedor.
Associar a origem autenticada à operadora, carteira, moeda e conta do jogador corretas.
Validar ID, precisão do valor, ação e referência do lançamento original.
Comparar os parâmetros com a impressão digital armazenada antes de reconhecer duplicidade.
Registre para auditoria apenas IDs seguros, horários e hashes, sem credenciais ou informações pessoais desnecessárias. Não responda sucesso a uma mensagem falsificada apenas porque o mesmo ID já foi contabilizado. [2] [6]
Qual é o fluxo completo de um callback seguro?
Depois da autenticação, a operadora procura ou reserva uma chave única de negócio, valida os parâmetros, aplica o lançamento permitido e salva seu resultado em uma transação durável de banco. Uma nova entrega com os mesmos dados recebe a decisão gravada em vez de alterar o saldo novamente. Estados ambíguos seguem para conciliação. [1] [4] [6]
Autenticar o callback, confirmar o provedor e localizar o jogador autorizado.
Construir a chave de negócio prevista e conferir a referência de eventual reversão.
Reservar ou consultar a operação de modo atômico, lançar uma única vez e gravar o resultado.
Responder conforme o provedor; investigar casos incertos sem criar novo efeito monetário.
⊕Ampliar diagramaVárias tentativas de entrega podem representar a mesma transação durável.
O commit do banco e o envio da resposta HTTP normalmente não são atômicos entre sistemas independentes. É preciso suportar o cenário em que o lançamento foi confirmado, mas a resposta se perdeu: o remetente repetirá a operação já concluída. [4] [7]
Como impedir lançamentos duplicados no banco?
Crie uma restrição real de unicidade para a chave de negócio e mantenha o recebimento, o efeito na carteira e o resultado final sob uma transação apropriada. Um SELECT isolado antes de um UPDATE não basta sob concorrência: dois workers podem observar a mesma chave livre. A unicidade no banco e o controle de acesso concorrente devem decidir. [3] [4]
Estado encontrado
Tratamento seguro
Falha para testar
Chave nova válida
Lançar e salvar uma vez
Primeiras entregas paralelas
Concluída, mesmos dados
Reutilizar resultado salvo
Sem crédito duplicado
Em processamento
Aguardar ou conciliar
Workers concorrentes
Mesma chave, outros dados
Rejeitar conflito
Valor ou jogador mudou
Rollback antes do commit
Permitir retry controlado
Queda após reservar chave
Uma caixa de entrada persistente ajuda, mas receber o evento não prova que o dinheiro foi movimentado. Conserve estado da transação, referência do livro-razão e resultado imutável. A reversão pode gerar movimento próprio ou alterar estado vinculado, conforme o contrato de cada API. [1] [3]
Qual resposta usar para duplicatas e retries conflitantes?
Para uma duplicata autenticada e já concluída, devolva o resultado inicial ou o código específico solicitado pelo parceiro. Não existe HTTP 200, 409 ou valor JSON universal para todas as APIs de cassino. St8, 7SoftTech e GR8 Tech documentam diferentes campos e semânticas de erro. [1] [2] [3]
Manter resposta coerente para o mesmo ID e a mesma intenção da transação.
Rejeitar ID repetido com valor, moeda, jogador ou ação incompatível.
Após commit com resposta perdida, recuperar o resultado original sem novo lançamento.
Separar recusas definitivas de falhas técnicas temporárias para orientar o envio seguinte.
Não reproduza um saldo antigo quando o contrato pedir saldo atual nem invente um erro de duplicidade. Confira regras do provedor para novas tentativas, estornos e negócios recusados. O método HTTP POST não transforma uma repetição arbitrária em operação segura. [2] [3] [7]
Quando tentar novamente, aguardar ou parar?
A estratégia depende do contrato de idempotência e da causa do erro. Timeout e certos erros temporários deixam indefinido o resultado anterior. Assinaturas inválidas, solicitações malformadas e recusas finais não devem gerar retries sem fim. Configure limite de tentativas, intervalo progressivo com jitter e um processo de conciliação. [4] [6] [7]
Situação
Resposta preferida
Motivo
Timeout após envio
Consultar ou repetir mesmo ID
Commit pode ter ocorrido
5xx / limite temporário
Retry limitado e contratual
Problema transitório
Assinatura inválida
Rejeitar e alertar
Origem não autenticada
Recusa definitiva
Parar segundo o contrato
Retry não muda a decisão
Resposta perdida após commit
Usar resultado armazenado
Impedir segundo lançamento
Separe a fila automática de retries das correções manuais. A equipe deve saber o que pode reenviar, quando consultar um status e quando abrir investigação. Nunca troque o ID de negócio apenas para forçar uma transferência de resultado incerto. [3] [4]
E se os callbacks chegarem fora de ordem?
Mensagens podem chegar fora de sequência, inclusive um cancelamento antes do débito original. Alguns contratos exigem guardar uma marca de estorno, impedindo que uma aposta cancelada seja lançada quando chegar atrasada. Outros provedores têm ciclos diferentes; códigos particulares de uma API não podem ser generalizados. [1] [2] [5]
Guardar referência da transação original e estado do negócio, não somente o horário da entrega.
Definir transições permitidas entre débito, crédito, cancelamento e ajuste por provedor.
Manter marca durável de cancelamento anterior ao original quando o contrato determinar.
Enviar referências inconclusivas para conciliação sem criar lançamentos artificiais.
Ordem de recebimento não equivale à ordem de negócio. Não organize movimentos financeiros apenas pelo horário informado pelo cliente remoto. Use IDs, dependências e o estado confiável do provedor ou da operadora. [2] [5]
Como conciliar e monitorar retries depois de falhas?
Um callback pode ser recebido, mas falhar antes do lançamento, ou ser confirmado sem que o parceiro receba a resposta. Acompanhe separadamente a entrega técnica e o registro financeiro. Compare operações incertas com o livro-razão e histórico do fornecedor, com processo claro para divergências. Atualizar o saldo na tela não é conciliação. [1] [3] [4]
Monitorar tentativas, duplicatas aceitas, assinaturas inválidas, conflitos de conteúdo e fila de conciliação por provedor.
Alertar sobre muitos timeouts, operações travadas, estornos antecipados e diferenças de saldo.
Restringir replay manual a pessoal autorizado com ID original e justificativa auditável.
Comparar lançamentos e registros do parceiro antes de autorizar movimento compensatório.
Manter o registro de deduplicação durante os prazos contratuais de retry e contestação.
Evite dados pessoais e financeiros brutos em ferramentas gerais de análise. Guarde IDs seguros, hashes, horários, mudanças de estado e ações de operadores, com acesso e retenção limitados. Diferencie volume de callbacks duplicados de divergências financeiras reais nos painéis de monitoramento. [4] [6]
Quais testes de aceite comprovam retries seguros?
Uma aposta e um prêmio corretos no caminho principal não demonstram proteção contra duplicatas. A certificação precisa cobrir IDs repetidos, conteúdos conflitantes, workers paralelos, respostas perdidas, estornos e eventos atrasados conforme o contrato. A 7SoftTech apresenta testes específicos de bet, win e cancel repetidos. [2]
Processar um débito ou crédito, reenviar o mesmo callback assinado e validar somente um lançamento.
Enviar o mesmo ID com outro valor, jogador ou moeda e confirmar rejeição controlada.
Executar duas entregas simultâneas, simular perda da resposta após commit e ler o resultado salvo.
Receber cancelamento antes do movimento original e verificar a regra do provedor.
Simular indisponibilidade, reenviar eventos atrasados e comparar livro-razão e evidências de auditoria.
Antes de publicar, valide com cada parceiro os formatos de resposta, escopo das chaves, horizonte de tentativas e regras de reversão. O sucesso não é zerar mensagens duplicadas, mas contabilizar corretamente cada operação autorizada uma única vez apesar de retries, respostas perdidas e entregas fora de ordem. [1] [3] [4]