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
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 webhookorder.paid é o mesmo gatilho — veja os guias específicos em FiveM e RedM e Minecraft e outros engines.