Eventos Disponíveis

Lista completa dos eventos disparados pelos webhooks da Cakto e seus identificadores.

O campo event está presente em todos os payloads e identifica o tipo de notificação recebida.

Referência de eventos

Evento	Descrição	Trigger
purchase_approved	Compra aprovada	Pagamento único ou recorrente aprovado
purchase_refused	Compra recusada	Tentativa de pagamento recusada
pix_gerado	Pix gerado	QR Code Pix criado, aguardando pagamento
boleto_gerado	Boleto gerado	Boleto emitido, aguardando pagamento
picpay_gerado	PicPay gerado	Cobrança PicPay criada, aguardando pagamento
refund	Reembolso	Pedido reembolsado
chargeback	Chargeback	Disputa de pagamento iniciada pelo cliente
subscription_canceled	Cancelamento	Assinatura recorrente cancelada
subscription_renewed	Renovação	Assinatura recorrente renovada com sucesso
checkout_abandonment	Abandono de checkout	Cliente preencheu dados mas não finalizou a compra

Como usar

{
  "secret": "sua-chave",
  "event": "purchase_approved",
  "data": { ... }
}

No seu servidor, filtre pelo campo event para rotear cada notificação:

app.post('/webhook', (req, res) => {
  const { secret, event, data } = req.body

  // Valide o secret primeiro
  if (secret !== process.env.WEBHOOK_SECRET) {
    return res.status(401).end()
  }

  switch (event) {
    case 'purchase_approved':
      handlePurchaseApproved(data)
      break
    case 'subscription_canceled':
      handleCancellation(data)
      break
    case 'checkout_abandonment':
      handleAbandonedCart(data)
      break
    // ...
  }

  res.status(200).end()
})

Sempre retorne uma resposta HTTP 200 o mais rápido possível. Se precisar de processamento demorado, salve o payload em uma fila e processe de forma assíncrona.