DOCS

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

EventoDescrição
charge.pendingPagamento em análise ou aguardando confirmação
charge.succeededPagamento confirmado pelo adquirente
charge.failedPagamento recusado (inclui Pix ou boleto expirado, por compatibilidade)
charge.expiredPix ou boleto venceu sem pagamento
charge.refundedReembolso 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.disputedContestaçã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_resolvedContestaçã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

EventoDescrição
checkout.initiatedO comprador começou a preencher o checkout
payment_info.addedO comprador escolheu a forma de pagamento (um evento por forma escolhida)
pix.generatedQR Code Pix emitido, aguardando pagamento
boleto.generatedBoleto emitido, aguardando pagamento

Assinaturas

EventoDescrição
subscription.renewedCiclo de assinatura pago
subscription.canceledAssinatura cancelada
subscription.payment_failedCobrança de renovação recusada (traz failure_code e failure_message)

Saques

EventoDescrição
payout.succeededSaque creditado na conta destino
payout.failedSaque 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 envio
  • v1 — 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:

TentativaEspera desde a anterior (aprox.)
1Imediata
22 minutos
34 minutos
48 minutos
516 minutos
632 minutos
764 minutos
8128 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_...');

On this page