Skip to main content
Nunca libere o produto na página de sucesso do checkout. O comprador pode fechar o navegador antes do redirect, e a confirmação de um PIX pode chegar minutos depois, fora do fluxo dele. A fonte da verdade sobre um pagamento é sempre o webhook.

Configurando um endpoint

Cadastre a URL do seu endpoint no painel (Loja → Configurações → Webhooks) e guarde o segredo gerado (whsec_...).

Eventos

Corpo recebido:

Validando a assinatura

Header enviado: X-Huskpay-Signature: t=1755280000,v1=5f3a9c... O v1 é HMAC-SHA256(segredo, "{t}.{corpo_cru}"). Use sempre o corpo cru da requisição, antes de qualquer parse de JSON — reserializar o corpo muda os bytes e a assinatura não bate mais.

Regras de entrega

Responda 2xx rápido

Processamento pesado deve ir para uma fila sua — o timeout do lado da loja.gg é de 15 segundos.

Entrega at-least-once

O mesmo id de evento pode chegar mais de uma vez. Guarde os ids processados e trate repetição como no-op.

Reenvio com backoff

Falhas são reagendadas em 1m → 5m → 30m → 2h → 6h → 24h. Depois disso a entrega fica exhausted e pode ser reenviada manualmente pelo painel.

Requisitos de rede

A URL precisa ser https na porta 443 e resolver para um IP público. Endereços internos (127.0.0.1, 10.x, 169.254.169.254) são recusados tanto no cadastro quanto em cada entrega. Redirecionamentos não são seguidos.
Um endpoint com falhas contínuas é desativado automaticamente, com aviso ao lojista.

Sem endpoint público? Use polling

Exige chave secreta e escopo webhooks:read.

Checklist antes de ir para produção

  • A chave secreta não aparece em nenhum lugar do bundle do front (grep -r "hk_live_sec" ./build)
  • O webhook valida a assinatura e a tolerância de 5 minutos
  • O webhook é idempotente por event.id
  • A entrega do produto acontece no order.paid, não na página de sucesso
  • Idempotency-Key é um UUID novo por tentativa de compra, reutilizado apenas nos retries
  • Os totais exibidos vêm de line_items / amount_total, não de cálculo próprio
  • Origens e URLs de retorno de produção estão cadastradas
  • Testado ponta a ponta com chaves hk_test_*

Entrega em servidor de jogo

Se o que você quer entregar é um item, VIP ou comando dentro de um servidor FiveM, RedM, Minecraft ou outro engine, o webhook order.paid é o mesmo gatilho — veja os guias específicos em FiveM e RedM e Minecraft e outros engines.