Webhooks
Receba notificações em tempo real sobre eventos na sua conta Kirvex.
Como funciona
Quando eventos acontecem na sua conta (pagamento confirmado, reembolso processado, etc.), a Kirvex envia um POST HTTP para as URLs que você configurar.
Eventos disponíveis
Pagamentos
| Evento | Descrição |
|---|---|
charge.pending | Pagamento em análise ou aguardando confirmação |
charge.succeeded | Pagamento confirmado pelo adquirente |
charge.failed | Pagamento recusado (inclui Pix ou boleto expirado, por compatibilidade) |
charge.expired | Pix ou boleto venceu sem pagamento |
charge.refunded | Reembolso processado. Para reembolsos assíncronos (Pix pela Woovi, boleto por Pix ao comprador) chega quando o reembolso é confirmado, não quando é pedido; um reembolso recusado não gera webhook (consulte GET /v1/refunds/:id) |
charge.disputed | Contestação/chargeback aberto — enviado uma vez, quando a contestação aparece em Disputas (depois da análise da equipe Kirvex, no máximo alguns dias antes do prazo de defesa) |
charge.dispute_resolved | Contestação encerrada, ganha ou perdida (data.outcome: won ou lost; data.dispute_status: won, lost ou expired). Sempre depois do charge.disputed da mesma contestação |
Checkout
| Evento | Descrição |
|---|---|
checkout.initiated | O comprador começou a preencher o checkout |
payment_info.added | O comprador escolheu a forma de pagamento (um evento por forma escolhida) |
pix.generated | QR Code Pix emitido, aguardando pagamento |
boleto.generated | Boleto emitido, aguardando pagamento |
Assinaturas
| Evento | Descrição |
|---|---|
subscription.renewed | Ciclo de assinatura pago |
subscription.canceled | Assinatura cancelada |
subscription.payment_failed | Cobrança de renovação recusada (traz failure_code e failure_message) |
Saques
| Evento | Descrição |
|---|---|
payout.succeeded | Saque creditado na conta destino |
payout.failed | Saque falhou |
Os eventos de checkout, charge.pending, charge.expired e os de assinatura
existem para vendas feitas pelo checkout hospedado da Kirvex (uma cobrança
criada direto em POST /v1/charges não passa pelo checkout) e chegam em até
cerca de um minuto depois do fato.
Um endpoint criado sem event_types (ou com a lista vazia) recebe todos os
eventos, inclusive os que forem criados no futuro. Novos tipos de evento podem
surgir a qualquer momento: ignore com 2xx os que você não trata.
Configuração
Via SDK (TypeScript)
const ep = await ap.webhookEndpoints.create({
url: 'https://seuapp.com/webhooks/kirvex',
event_types: ['charge.succeeded', 'charge.failed', 'charge.refunded'],
});
// Guarde o secret — ele só é mostrado uma vez
console.log(ep.secret); // whsec_...
Via SDK (PHP)
$ep = $ap->webhookEndpoints->create([
'url' => 'https://seuapp.com/webhooks/kirvex',
'event_types' => ['charge.succeeded', 'charge.failed'],
]);
Via SDK (Python)
ep = ap.webhook_endpoints.create({
"url": "https://seuapp.com/webhooks/kirvex",
"event_types": ["charge.succeeded", "charge.failed"],
})
Verificação de assinatura
Toda requisição webhook inclui o header X-Kirvex-Signature no formato:
t=1714432800,v1=5d41402abc4b2a76b9719d911017c592
t— timestamp Unix (segundos) do enviov1— HMAC-SHA256 de{timestamp}.{body}com o secret do endpoint
TypeScript
import { createHmac, timingSafeEqual } from 'node:crypto';
function verifyWebhook(rawBody: string, sigHeader: string, secret: string): boolean {
const parts = Object.fromEntries(
sigHeader.split(',').map(p => p.split('=', 2) as [string, string])
);
const expected = createHmac('sha256', secret)
.update(`${parts.t}.${rawBody}`)
.digest('hex');
return timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}
PHP
use Kirvex\Sdk\WebhookHelper;
$event = WebhookHelper::verify(
file_get_contents('php://input'),
$_SERVER['HTTP_X_KIRVEX_SIGNATURE'],
'whsec_...'
);
Python
from kirvex import verify_webhook
event = verify_webhook(
raw_body=request.body,
signature=request.headers["x-kirvex-signature"],
secret="whsec_...",
)
Retries
Uma entrega conta como sucesso quando o seu endpoint responde com qualquer
status 2xx em até 5 segundos. Qualquer outra resposta (3xx, 4xx, 5xx)
ou a falta de resposta é reenviada com espera crescente:
| Tentativa | Espera desde a anterior (aprox.) |
|---|---|
| 1 | Imediata |
| 2 | 2 minutos |
| 3 | 4 minutos |
| 4 | 8 minutos |
| 5 | 16 minutos |
| 6 | 32 minutos |
| 7 | 64 minutos |
| 8 | 128 minutos |
As esperas têm uma variação de até 10% para cima ou para baixo. Após 8 tentativas sem sucesso o evento vai para a DLQ (dead letter queue), visível em Configurações → Webhooks → Entregas falhas, de onde pode ser reenviado.
Idempotência
Cada evento tem um id único. Seu handler deve ser idempotente — o mesmo evento pode ser entregue mais de uma vez (retry ou replay manual).
// Exemplo: use o event.id como chave de idempotência
const alreadyProcessed = await db.processedEvents.findUnique({ where: { id: event.id } });
if (alreadyProcessed) return res.status(200).end();
Payload
{
"id": "evt_01J...",
"type": "charge.succeeded",
"created": "2026-04-29T12:00:00.000Z",
"livemode": true,
"data": {
"charge_id": "ch_01J...",
"status": "succeeded",
"amount": { "amount": "9990", "currency": "BRL" },
"vendor": "...",
"vendor_ref": "...",
"order_id": "ord_01J...",
"checkout_session_id": "cs_01J...",
"products": [
{
"product_id": "prod_01J...",
"name": "Curso completo",
"quantity": 1,
"unit_amount": { "amount": "9990", "currency": "BRL" }
}
],
"tracking": {
"utm_source": "anuncio",
"utm_medium": "cpc",
"utm_campaign": "lancamento",
"utm_content": "video-1",
"utm_term": null,
"fbclid": "abc123...",
"gclid": null,
"ttclid": null,
"src": null,
"sck": null
}
}
}
Bloco tracking
Todo evento charge.*, de checkout e de assinatura traz data.tracking com a
origem da visita que gerou a venda, capturada na primeira visita ao checkout:
utm_source, utm_medium, utm_campaign, utm_content, utm_term,
fbclid, gclid, ttclid, src e sck. As dez chaves estão sempre
presentes; o valor é null quando a visita não trouxe o parâmetro ou quando a
cobrança foi criada direto pela API. order_id, checkout_session_id e
products vêm quando há pedido (null / lista vazia quando não há).
Eventos de checkout e assinatura
{
"id": "evt_01J...",
"type": "pix.generated",
"created": "2026-04-29T12:00:05.000Z",
"livemode": true,
"data": {
"checkout_session_id": "cs_01J...",
"checkout_id": "chk_01J...",
"funnel_event_id": "cke_...",
"occurred_at": "2026-04-29T12:00:00.000Z",
"amount": { "amount": "9990", "currency": "BRL" },
"charge_id": "ch_01J...",
"method": "pix",
"order_id": "ord_01J...",
"products": [],
"tracking": { "utm_source": "anuncio", "utm_medium": "cpc", "...": null }
}
}
funnel_event_id é o mesmo identificador enviado aos pixels de anúncio, útil
para cruzar os dois lados. subscription.* traz também subscription_id e
invoice_id; subscription.payment_failed traz attempt, failure_code e
failure_message; subscription.canceled traz reason. O amount pode ser
null (por exemplo em checkout.initiated antes do valor final).
livemode diz de qual modo é o evento: false para uma cobrança criada com
uma chave sk_test_ (sandbox, sem dinheiro real), true para uma cobrança
real. Os mesmos endpoints recebem os dois — filtre por livemode antes de
liberar um pedido. Eventos de saque são sempre livemode: true.
Test Send
Envie um evento de teste para validar sua integração:
await ap.webhookEndpoints.testSend('we_...');