Pular para o conteúdo principal

Webhooks

Os webhooks levam os eventos ao seu backend na hora: transações, resultados de KYC, créditos no cofre, mudanças de situação de cartões e pedidos. Eles são a base de uma experiência de cartão que responde rápido.

API v1 · Legado

Esta página faz parte da referência da primeira versão da API da Web3Card, mantida aqui para consulta. A API v1 não recebe integrações novas: a API v2 a substitui, e a plataforma hoje funciona como descrito no resto deste manual.

Assine​

Cadastre o seu endereço e escolha os eventos que quer receber:

curl -X POST https://api.web3card.dev/v1/webhooks \
  -H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.yourproject.com/hooks/web3card",
    "events": ["transaction.*", "kyc.*", "vault.credited", "card_order.updated"]
  }'
{ "id": "wh_2210", "status": "active", "secret": "whsec_9k3j…" }

Confira as assinaturas​

Toda entrega é assinada. Calcule um HMAC SHA-256 do corpo bruto com o segredo do seu webhook e compare com o cabeçalho X-W3C-Signature:

const crypto = require("crypto");

function verify(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Recuse toda entrega cuja assinatura não bata.

Catálogo de eventos​

EventoSai quando
transaction.createdUma autorização nova é aprovada ou recusada
transaction.updatedUma transação muda de situação (liquidada, estornada, contestada…)
vault.creditedUma recarga é creditada num cofre
vault.debitedUma liquidação ou um saque sai de um cofre
kyc.approvedVerificação de identidade aprovada
kyc.rejectedVerificação de identidade recusada
card.updatedMudança de situação do cartão (congelado, perdido, anulado…)
card_order.updatedO pedido de cartão físico avança

Entrega e novas tentativas​

As entregas esperam uma resposta 2xx em até 10 segundos. As que falham são repetidas com intervalo crescente por até 24 horas. Cada evento chega pelo menos uma vez; use o id do evento para não processar duas vezes.

Última atualização em