Webhooks — Visão Geral

Webhooks permitem que você receba notificações em tempo real sobre mudanças de status de suas transações, sem precisar fazer polling na API.

Como Funciona

  1. Configure uma URL de webhook no seu dashboard ou via API
  2. Quando um evento ocorrer, enviamos uma requisição POST para sua URL com o payload do evento
  3. Valide a assinatura HMAC para garantir autenticidade
  4. Processe o evento e retorne HTTP 200

Dois Modos de Notificação

1. Webhook Global (Dashboard ou API)

Configure webhooks globais que serão enviados para todas as cobranças do seller:

POST /v1/webhooks

{
  "url": "https://seusite.com.br/webhook",
  "events": ["charge.paid", "charge.failed"]
}

2. Callback URL Pontual (por Cobrança)

Envie um callback_url no payload de criação da cobrança para receber notificações apenas desta cobrança específica. Ideal para integrações diretas onde cada pedido tem sua própria URL de retorno:

POST /v1/charges

{
  "amount": 10000,
  "payment_method": "pix",
  "callback_url": "https://seusite.com.br/pagamento/callback.php",
  "customer": { ... }
}

Payload do callback_url (PIX)

Quando o pagamento PIX for confirmado, sua URL receberá:

{
  "id": "ci_k7m2p9xr4nqs",
  "status": "paid",
  "amount": 10000,
  "txid": "E12345678202511281234567890123456"
}
⚠️ Atenção — Identificação do Pedido via callback_url:

O campo id no payload é o identificador único da ApexPy (ci_...). Sempre armazene o pix.txid retornado na criação da cobrança e use-o como fallback de busca no seu banco de dados, pois o txid é imutável e emitido pelo sistema bancário.

Recomendação de lookup no callback: 
// Tente primeiro pelo id da ApexPy
$pedido = buscarPor('transaction_id', $dados['id']);

// Se não encontrar, tente pelo txid bancário (PIX)
if (!$pedido && !empty($dados['txid'])) {
    $pedido = buscarPor('pix_txid', $dados['txid']);
}

Eventos Disponíveis

Evento Descrição
charge.created Cobrança criada
charge.paid Cobrança paga
charge.failed Cobrança falhou
charge.refunded Cobrança reembolsada
charge.cancelled Cobrança cancelada
payout.created Saque criado
payout.completed Saque concluído
payout.failed Saque falhou

Boas Práticas