Webhooks de pagamento cripto: eventos, segurança e entrega confiável de pedidos

Webhooks de pagamento cripto são requisições HTTP que o gateway envia ao seu servidor sempre que uma fatura muda de status: transferência detectada, confirmada na blockchain, paga a menor, a maior ou expirada. Seu handler verifica a assinatura, atualiza o pedido e dispara a entrega. Como pagamentos cripto chegam de forma assíncrona, minutos depois de o cliente sair da página, a fonte da verdade é o webhook, não o navegador.

Este guia foca no lado dos webhooks de uma integração: os eventos esperados, como verificá-los, como processar com segurança quando o mesmo evento chega duas vezes e como testar e monitorar. Para criar faturas, veja nosso guia de integração com a API de pagamento cripto.

Por que webhooks em vez de polling ou redirecionamento?

• Redirecionamento não é prova — o cliente voltar à página de «obrigado» não diz nada sobre o dinheiro ter chegado.
• Polling é desperdício — consultar a API a cada poucos segundos para cada fatura aberta não escala e ainda atrasa.
• Webhooks são push — o gateway avisa no momento em que algo muda, com uma assinatura verificável.

Os eventos que você vai receber

Estes são os nomes de evento da mistKET. Outros gateways usam status parecidos com nomes diferentes; mapeie-os para os estados do seu pedido num único lugar.

Verificando a assinatura

Qualquer um pode enviar um POST para uma URL pública, então todo webhook precisa ser autenticado. A mistKET assina cada entrega com HMAC-SHA256 e envia estes cabeçalhos:

• X-Mistket-Event — nome do evento.
• X-Mistket-Timestamp — horário Unix incluído na assinatura.
• X-Mistket-Signature — sha256= seguido do HMAC de {timestamp}.{raw body} com seu segredo de webhook.
• X-Mistket-Delivery — ID da entrega para logs.

1. Leia o corpo bruto — antes de fazer parse do JSON, pois recodificar altera os bytes.
2. Recalcule o HMAC — sobre o timestamp, um ponto e o corpo bruto, com seu segredo.
3. Compare em tempo constante — use hash_equals, hmac.compare_digest ou crypto.timingSafeEqual.
4. Rejeite timestamps antigos — por exemplo, com mais de cinco minutos, para bloquear replays.
5. Só então faça parse e aja — e responda 2xx rapidamente.

A construção segue o padrão HMAC; mantenha o segredo no servidor e troque-o se vazar.

Escolhendo e protegendo a URL de callback

Use um caminho HTTPS dedicado, como /webhooks/mistket, separado das páginas comuns, e informe-o como callback ao criar cada fatura. Exclua-o de proteção CSRF, cache e redirecionamentos; um 301 ou uma resposta em cache é causa comum de webhooks falhando em silêncio. Não exija cookie de sessão: o gateway não é um usuário logado, e a autenticação é a assinatura HMAC. Por fim, registre cada entrega com evento, ID do pedido e código de resposta para responder «o webhook chegou?» em segundos.

Idempotência: o mesmo evento pode chegar duas vezes

Se seu endpoint demora ou retorna erro, o gateway tenta de novo com intervalos crescentes por horas. Falhas de rede também podem entregar um evento já processado. Por isso o handler precisa ser idempotente:

• Use o ID do pedido como chave — localize o pedido referenciado pela fatura.
• Confira o estado atual — se já foi entregue, confirme o recebimento e não faça mais nada.
• Use transação ou lock — para que duas entregas paralelas não enviem o produto duas vezes.
• Guarde o ID da entrega — útil para depurar duplicados.

Desenhando os estados do pedido a partir dos eventos

Uma máquina de estados simples evita a maioria dos bugs: pendente → confirmando (com paid) → pago (com confirmed) → entregue, com ramos para pago a menor e expirado. Permita apenas transições para frente. Um invoice.paid que chega depois do invoice.confirmed nunca deve fazer o pedido voltar. Pagamentos atrasados em faturas expiradas devem gerar um registro para análise em vez de reabrir o pedido em silêncio.

Tratando os casos chatos

• Pago a menor — informe ao cliente o valor exato que falta e que ele pode enviar para a mesma página de pagamento; pagamentos parciais somam.
• Pago a maior — entregue e depois decida entre crédito ou transferência de reembolso conforme sua política.
• Expirado — libere o estoque e ofereça uma nova fatura se o cliente ainda quiser comprar.
• Rede errada — resolvido pelo suporte, não pelo código; mostre a rede claramente no checkout para evitar.

Testes e monitoramento

1. Exponha um endpoint de teste — via HTTPS, registrando cabeçalhos e corpos brutos.
2. Dispare cada evento — paid, confirmed, underpaid, overpaid e expired, com pequenos pagamentos reais.
3. Reenvie uma entrega — confirme que o handler ignora o duplicado.
4. Quebre a assinatura — altere um byte e veja a requisição ser rejeitada.
5. Acompanhe os logs de entrega — o painel mostra cada tentativa, código de resposta e hash da transação.
6. Crie alertas de falha — um pico de respostas não 2xx significa pedidos sem entrega.

Bots e comunidades pagas seguem o mesmo padrão; veja como isso se encaixa num chat em aceitar pagamentos cripto num bot do Telegram.

Webhooks com a mistKET

A mistKET envia webhooks assinados com HMAC para cada status de fatura, reenvia entregas que falharam com intervalos crescentes e mostra no painel os logs de entrega, valores esperados e recebidos e hashes de transação. As requisições à API são assinadas do mesmo jeito, então uma única função cobre os dois sentidos.

Veja exemplos de requisições e webhooks na seção para desenvolvedores, confira os preços e gerencie as chaves pelo login do lojista. Para obter acesso, candidate-se pelo Telegram em @mistnetwork.