Webhook de pagamentos cripto: como processar id e status
Guia do webhook de pagamentos cripto: receba o status final em um POST com id e status, valide o cabeçalho x-api-key e atualize pedidos com segurança.
Um webhook de pagamentos cripto informa ao seu backend o status final de um pagamento. Na Qvard é um POST com o id do seu pedido e o status, então a lógica do pedido atualiza sem consultar a API em loop.
O que o webhook envia
A Qvard chama a sua URL de webhook com uma requisição POST. O corpo traz o id que você enviou ao criar o pagamento e o status, por exemplo paid. A requisição leva o seu token x-api-key no cabeçalho.
Confira o cabeçalho x-api-key
Antes de confiar na mensagem, compare o cabeçalho x-api-key com o token da sua conta. Rejeite requisições sem ele, para que ninguém consiga marcar um pedido como pago chamando o seu endpoint diretamente.
x-api-key: sk_live_…
{ "id": "order_1024", "status": "paid" }Atualize o pedido pelo id
Localize o pedido pelo id do corpo e altere o estado conforme o status. Marque o pedido como pago somente quando o status for paid e ignore os status que o seu sistema não trata.
Faça o manipulador suportar repetição
O mesmo webhook pode chegar mais de uma vez. Guarde o id e o status já processados e não faça nada se o evento já foi tratado. Responda com um código de sucesso depois de salvar a alteração.
Responda rápido e enfileire o trabalho lento
Confirme o webhook assim que o pedido estiver salvo. Envie e-mails, faturas e chamadas ao estoque por um job em segundo plano, para que um passo lento nunca cause timeout.
Teste com uma fatura de demonstração
Crie uma fatura de demonstração, pague na página hospedada e observe o seu endpoint receber o webhook antes de ir para produção.
FAQ
Qual é a diferença entre a resposta da API e o webhook?
A resposta da API confirma que o pagamento foi criado e devolve um redirectUrl. Só o webhook informa o status final do pagamento.
O que acontece se o meu endpoint estiver fora do ar?
A entrega é repetida, então o seu manipulador precisa suportar repetição. Confira os logs com regularidade e concilie os pedidos que ficaram pendentes.
Posso confiar num webhook sem o x-api-key?
Não. Confira sempre o cabeçalho x-api-key antes de alterar um pedido.
Quais status devo tratar?
Trate paid para pagamentos concluídos e considere qualquer outro status apenas como informação. A documentação da API lista o conjunto completo de valores.
