Webhooks
Seu sistema sabe assim que acontece.
Cadastre uma URL e receba um evento assinado sempre que um pagamento, assinatura, reembolso, saque ou disputa mudar de estado.
import crypto from 'node:crypto';
// secret: whsec_... da inscrição; body: corpo bruto, sem parse
export function isValidWebhook(headers, body, secret) {
const id = headers['svix-id'];
const ts = headers['svix-timestamp'];
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
return false;
}
const key = Buffer.from(secret.split('_')[1], 'base64');
const expected = crypto
.createHmac('sha256', key)
.update(`${id}.${ts}.${body}`)
.digest('base64');
return headers['svix-signature']
.split(' ')
.map((entry) => entry.split(',')[1] ?? '')
.some((signature) => safeEqual(signature, expected));
}
function safeEqual(a, b) {
return a.length === b.length &&
crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b));
}O essencial, bem feito.
- Eventos versionados
- payment.succeeded.v1, refund.succeeded.v1, payout.updated.v1 e outros. O sufixo garante que o formato não muda sem aviso.
- Assinatura em cada entrega
- Cabeçalhos svix-id, svix-timestamp e svix-signature, com HMAC-SHA256 sobre o corpo para você validar a origem.
- Reenvio automático
- Se o seu servidor estiver fora do ar, a entrega é tentada de novo. O histórico de entregas fica no painel.
- Simulação nos testes
- No ambiente de testes você dispara eventos de um pagamento para validar o seu endpoint antes de ir para produção.
Como funciona
- 1Cadastre a URL e escolha os eventos no painel ou pela API.
- 2Valide a assinatura de cada entrega.
- 3Responda 2xx rapidamente e processe em segundo plano.
Perguntas frequentes
Quais eventos existem?
Pagamentos (criado, aguardando ação, aprovado, falhou), assinaturas, reembolsos, saques, disputas e mudanças de status e de verificação da conta.
Posso ter mais de um endpoint?
Sim. Cada inscrição tem a sua URL, os seus eventos e o seu segredo, e pode ser desativada a qualquer momento.
Outros recursos
- API de pagamentosREST, OpenAPI 3.1, chaves com escopo e idempotência.Conhecer
- Ambiente de testesSandbox completo com cenários simulados, sem dinheiro real.Conhecer
- CommerceProdutos, ofertas, pedidos e clientes pela API.Conhecer
- IntegraçõesPixels de anúncio, origem das vendas, área de membros e IA.Conhecer
Comece a receber em poucos minutos.
Crie a conta, teste no ambiente de testes e publique o checkout quando estiver pronto.