Saiba na hora quando o Pix é pago.
Cadastre a URL do seu servidor e receba o evento de pagamento, com assinatura para validar a origem, reenvio automático e um painel de entregas.
- Evento transaction.paid
- Até 5 tentativas
- Assinatura HMAC
Em resumo
- O que é
- Webhooks são avisos que a Quibly Pay envia ao seu servidor quando um pagamento é confirmado (evento transaction.paid), com assinatura HMAC, até 5 tentativas de entrega e reenvio pelo painel.
- Para quem é
- Desenvolvedores e quem liga a Quibly Pay a um sistema próprio, CRM ou automação.
- Quanto custa
- Sem mensalidade: você paga só quando vende, R$ 1,00 por Pix pago e 4,99% da venda no cartão de crédito à vista.
Como funciona
Cadastre o webhook
Em Desenvolvedor > Webhooks, informe a URL pública em HTTPS, escolha os eventos e defina um segredo.
Receba o evento
Quando um pagamento é confirmado, a Quibly Pay faz um POST na sua URL com o corpo do evento e cabeçalhos de segurança.
Valide a origem
Compare o segredo do cabeçalho ou, se preferir, confira a assinatura HMAC-SHA256 do corpo cru.
Responda e acompanhe
Responda com qualquer status 2xx. Se não houver resposta, a entrega é refeita, e você acompanha e reenvia pelo painel.
Veja no código
{
"event": "transaction.paid",
"transactionId": "TRANSACTION_ID",
"externalRef": "PROVIDER_REFERENCE",
"amount": 25,
"netAmount": 24,
"tax": 1,
"status": "PAID",
"type": "DEPOSIT",
"confirmed_date": "2026-10-04 12:00:00"
}Trecho da documentação (Payload). A tarifa do exemplo é ilustrativa, não uma promessa de preço.
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verifyQuibly(rawBody, timestamp, signature, secret) {
// rawBody deve ser o Buffer original, sem usar JSON.stringify(parsedBody).
if (!/^\d+$/.test(timestamp ?? '') || !/^sha256=[a-f0-9]{64}$/.test(signature ?? ''))
return false;
const seconds = Number(timestamp);
if (!Number.isSafeInteger(seconds) || Math.abs(Date.now() / 1000 - seconds) > 300) return false;
const expected = createHmac('sha256', secret)
.update(timestamp + '.')
.update(rawBody)
.digest();
const received = Buffer.from(signature.slice(7), 'hex');
return received.length === expected.length && timingSafeEqual(expected, received);
}Trecho da documentação (Verificação HMAC). Use o corpo cru da chamada e a chave de assinatura do webhook.
O que você tem
Evento de pagamento
transaction.paid, com o identificador da transação, valor, valor líquido, tarifa, status e data de confirmação.
Assinatura HMAC-SHA256
Cada webhook tem a própria chave de assinatura, revelada com o segundo fator e que pode ser trocada.
Segredo no cabeçalho
O X-Quibly-Secret traz o segredo do webhook, só para o endereço cadastrado.
Até 5 tentativas
Imediata e depois após 1, 5, 15 e 60 minutos. Cada entrega espera até 15 segundos pela sua resposta.
Identificador estável
O X-Quibly-Event-Id é o mesmo em todas as tentativas, para você ignorar repetições.
Painel de entregas
Veja cada entrega, busque, reenvie uma delas agora ou reenvie todas as que falharam.
Teste de envio
Dispare um evento de teste para a sua URL antes de ligar tudo.
Aviso por cobrança
Marque um webhook para as notificações por cobrança, usadas pelo urlnoty da API Pix.
Para quem é
Quem libera o pedido por código
Receba o aviso de pagamento e libere o acesso, o produto ou a entrega.
Quem integra a API Pix
Complemente a consulta de status com o aviso em tempo real.
Quem precisa de segurança na entrada
Valide a origem pelo segredo ou pela assinatura antes de processar.
Perguntas frequentes
Quais eventos existem?
Hoje o evento de transação é transaction.paid, para depósitos e saques pagos. Não há eventos de estorno, chargeback ou Pix expirado.
Como valido que a chamada veio da Quibly Pay?
Compare o cabeçalho X-Quibly-Secret com o segredo do webhook ou, em outra origem, confira a assinatura HMAC-SHA256 do corpo cru com a chave de assinatura.
E se o meu servidor estiver fora do ar?
A Quibly Pay tenta até 5 vezes, com espera crescente. Depois disso, você pode reenviar a entrega pelo painel. Como pode haver repetição, ignore eventos com o mesmo X-Quibly-Event-Id.
Posso cadastrar vários webhooks?
Sim, até o limite de endpoints da sua conta. Cada webhook escolhe os eventos que recebe.
O webhook avisa vendas do ambiente de teste?
Os webhooks cadastrados recebem eventos de produção. No teste, o aviso vai para a URL informada na cobrança ou na credencial.
Veja também
Comece grátis, sem mensalidade.
Crie a conta e configure o seu primeiro produto. Você só paga quando vende.