Webhooks e eventos

O Tokia envia webhooks para notificar sua aplicacao sobre eventos importantes: recargas, uso de credito, saldo baixo e mudancas de conta. Use webhooks para manter seu sistema sincronizado com o estado do Tokia em tempo real.

Eventos disponiveis

Evento	Quando dispara	Dados principais
`topup.confirmed`	Recarga confirmada (PIX ou cartao)	valor, metodo, saldo atualizado
`usage.created`	Nova chamada de API reconciliada	modelo, tokens, custo BRL, chave
`balance.low`	Saldo caiu abaixo do limite configurado	saldo atual, limite
`account.suspended`	Conta suspensa (fraude, saldo negativo)	motivo, data
`subscription.created`	Novo plano ativado	plano, valor, ciclo
`subscription.canceled`	Plano cancelado	plano, data efetiva

Formato do payload

Todo webhook e enviado como POST com body JSON. O formato segue um envelope padrao:

json

{
  "event": "topup.confirmed",
  "created_at": "2026-10-03T14:30:00.000Z",
  "data": {
    "amount_brl": 50.00,
    "method": "pix",
    "balance_brl": 150.00,
    "topup_id": "top_abc123"
  }
}

Headers

Header	Descricao
`Content-Type`	`application/json`
`X-Tokia-Signature`	HMAC-SHA256 do body com seu signing secret
`X-Tokia-Event`	Nome do evento (ex: `topup.confirmed`)

Validacao de assinatura

Sempre valide o header X-Tokia-Signature antes de processar o webhook. O signing secret esta disponivel no painel de configuracoes.

typescript

import { createHmac } from "node:crypto";

function validateSignature(body: string, signature: string, secret: string): boolean {
  const expected = createHmac("sha256", secret).update(body).digest("hex");
  return expected === signature;
}

const body = await request.text();
const signature = request.headers.get("x-tokia-signature") ?? "";

if (!validateSignature(body, signature, process.env.TOKIA_WEBHOOK_SECRET!)) {
  return new Response("Invalid signature", { status: 401 });
}

const event = JSON.parse(body);

Voce tambem pode usar o testador de assinatura para debugar sua implementacao.

Retry automatico

Se seu endpoint retornar um codigo de erro (5xx) ou nao responder em 10 segundos, o Tokia faz ate 3 retries com backoff exponencial:

1a retry: 30 segundos depois
2a retry: 5 minutos depois
3a retry: 30 minutos depois

Se todas as tentativas falharem, o evento e descartado. Recomendamos implementar idempotencia no seu handler (usando o event_id do payload) para lidar com entregas duplicadas.

Boas praticas

Responda com 200 OK o mais rapido possivel — processe o evento em background
Valide a assinatura em toda requisicao
Implemente idempotencia (mesmo evento processado 2x nao deve causar efeito duplicado)
Monitore falhas de webhook no painel
Use HTTPS — o Tokia nao envia webhooks para endpoints HTTP sem TLS