Segurança de webhooks de pagamento: assinaturas, replays e novas tentativas

Proteja webhooks da Suawave com RSA-SHA256, bytes originais, vínculo ao pedido, idempotência durável e confirmação correta de recebimento.

Publicado em , atualizado em

Notebook, cadeado e cabo organizado sobre uma mesa representam a verificação segura de webhooks

Proteger um webhook significa verificar a requisição antes de confiar nela, vincular o pagamento ao pedido e registrar seus efeitos uma única vez. Na Suawave, verifique x-ca-signature com RSA-SHA256, preserve os bytes assinados e deduplique UUIDs de forma durável. Retorne HTTP 200 com *ok* somente depois de aceitar o evento em processamento persistente.

O processador precisa funcionar quando uma requisição legítima chega duas vezes, quando dois depósitos chegam juntos e quando o processo para após o commit. A assinatura resolve apenas parte desse trabalho.

1. Preserve os bytes antes da verificação

Os callbacks públicos usam RSA-SHA256 em base64 com PKCS#1 v1.5. Obtenha o PEM PKIX PUBLIC KEY por GET /pubkey/ em HTTPS. Exija RSA de pelo menos 2048 bits e armazene em cache. O verificador não precisa de segredo HMAC nem da chave privada.

Transporte Mensagem assinada Erro comum
GET padrão URL externa completa com consulta original Ordenar ou recodificar parâmetros
POST com post=1 Corpo bruto exato Reconstruir o formulário
JSON POST com json=1 Corpo bruto exato Serializar o JSON interpretado novamente

json=1 tem precedência. A primeira chamada create fixa as opções do par ticker/callback; repetir create não reconfigura um pedido existente.

Atrás de um proxy, combine uma origem externa confiável configurada com o destino original codificado da requisição. Não confie em Host ou cabeçalhos encaminhados fornecidos pelo chamador. Capture POST antes do middleware. Consulte a documentação de assinatura.

Verificador curto em Node.js

A função abaixo vem do exemplo JavaScript da documentação. Não é um handler HTTP completo. Carregue e valide a chave separadamente; passe o destino original e um Buffer com o corpo intacto.

const crypto = require('crypto');

function verifyCallback({ method, requestUri, rawBody, signature }, publicKeyPem, trustedOrigin) {
  let signed;
  if (method === 'GET') {
    signed = Buffer.from(trustedOrigin + requestUri, 'utf8');
  } else if (method === 'POST') {
    if (!Buffer.isBuffer(rawBody) || rawBody.length > 65536) return false;
    signed = rawBody;
  } else {
    return false;
  }
  if (!signature || !/^[A-Za-z0-9+/]+={0,2}$/.test(signature)) return false;
  const verifier = crypto.createVerify('RSA-SHA256');
  verifier.update(signed);
  return verifier.verify(publicKeyPem, signature, 'base64');
}

module.exports = { verifyCallback };

No Express, use req.originalUrl e capture POST com express.raw antes de interpretar. Limite também o tamanho na entrada HTTP. Trate erros de chave e verificação como falha: HTTP 401, sem alterar pedidos. Veja os exemplos em outras linguagens.

2. Vincule o pagamento ao pedido

Após verificar, interprete e encontre o pedido. Confira nonce, referência, address_in e coin. Um pedido trc20/usdt espera trc20_usdt no callback. Não deduza o ticker pelo valor ou por um rótulo do cliente.

POST assina o corpo; os parâmetros personalizados permanecem na URL. A assinatura não torna uma referência arbitrária nessa consulta confiável. Vincular endereço verificado e coin ao pedido evita aplicar um corpo legítimo a outra compra.

Gere um nonce imprevisível por pedido e mantenha a URL completa no servidor. Ela também dá acesso aos logs: não a inclua em analytics ou links ao cliente. O nonce ajuda no vínculo, mas não comprova que um evento capturado é recente.

Confira pending antes de aplicar valores. Um evento pendente legítimo não autoriza entrega; um confirmado ainda exige conferência do total. Consulte pagamentos a menos.

3. Evite replays com idempotência durável

Callbacks públicos não têm timestamp nem ID de chave. Não invente uma janela de cinco minutos com um cabeçalho inexistente. Uma requisição capturada pode continuar válida; processá-la novamente precisa ser inofensivo.

Salve UUID, pagamento e transição do pedido na mesma transação, com restrição de unicidade para UUID. Consultar antes se ele existe não elimina corridas.

  1. Insira o UUID verificado; conflito de unicidade significa evento já aceito.
  2. Bloqueie o pedido e registre o valor confirmado quando aplicável.
  3. Aplique somente transições que avancem o estado e crie uma tarefa durável de entrega.
  4. Faça commit antes da confirmação de recebimento.

Se a transação falhar, não reconheça sucesso. Se o commit funcionar mas a conexão cair, a repetição encontra o UUID salvo e confirma sem repetir efeitos.

O UUID sozinho evita entregas duplicadas?

Ele evita repetir o mesmo evento. Dois pagamentos reais têm eventos diferentes; a entrega também precisa de proteção por pedido, com uma tarefa persistente única. Os workers devem preservar essa regra ao chamar sistemas externos.

Pendente e confirmado do mesmo depósito têm UUIDs diferentes. Mantenha estado por depósito e não deixe um pendente atrasado desfazer a confirmação. Veja finalidade.

4. Confirme corretamente e espere novas tentativas

Responda HTTP 200 com corpo simples *ok* em até 30 segundos. ok sem asteriscos também é aceito, sem distinção de caixa. HTTP 204, JSON de sucesso ou redirecionamento não equivalem a essa resposta. Redirecionamentos não são seguidos; configure o destino HTTPS final.

São oito tentativas: envio inicial e intervalos de 30 segundos, 2 minutos, 10 minutos, 30 minutos, 2 horas, 6 horas e 24 horas, com até 10% de variação adicional. O UUID não muda. São intervalos sucessivos, não horários exatos prometidos.

Tire trabalho lento da requisição. Salve evento e tarefa de entrega de forma durável, reconheça e processe embalagem, e-mail ou acesso depois. Uma fila somente em memória pode perder a tarefa após confirmar.

O guia de callbacks detalha essas regras. Um evento válido já processado deve receber sucesso normal para encerrar as tentativas.

5. Trate rotação de chaves

Use cache da chave obtida no endpoint configurado. Se a assinatura falhar, atualize uma vez e tente novamente antes de rejeitar. A rotação também usa a nova chave nas novas tentativas de eventos antigos; o UUID continua identificando o evento.

Não obtenha chave de uma URL enviada pelo callback nem atualize repetidamente a mesma requisição. Valide tipo e tamanho da nova chave. Se o endpoint estiver indisponível, mantenha o pedido intacto e permita nova tentativa.

Separe registros operacionais de assinatura inválida dos de eventos válidos que não puderam ser salvos. Evite registrar URLs completas com segredos ao diagnosticar.

6. Concilie callbacks ausentes e teste falhas

Consulte GET /{ticker}/logs/ com o callback original. sent significa repasse confirmado sem reconhecimento do callback, inclusive com tentativas esgotadas; done indica reconhecimento. Logs são alternativa de conciliação, enquanto o fluxo normal usa callbacks verificados.

Antes de publicar, entregue o mesmo evento duas vezes e exija uma única ação persistente. Altere um byte e exija rejeição. Simule falha antes do commit, perda da resposta depois do commit e confirmado chegando antes de pendente.

Teste também dois pedidos distintos: assinatura válida de um depósito não pode pagar o outro. O guia USDT mostra o vínculo e TRC20 e BEP20 explica por que a rede deve acompanhar o valor.