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

Configure uma URL de webhook no seu dashboard ou via API
Quando um evento ocorrer, enviamos uma requisição POST para sua URL com o payload do evento
Valide a assinatura HMAC para garantir autenticidade
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

Valide a assinatura de todo webhook recebido antes de processá-lo (ver segurança)
Retorne HTTP 200 o mais rápido possível — processe em background se necessário
Implemente idempotência — o mesmo evento pode ser entregue mais de uma vez
Armazene o pix.txid na criação de cobranças PIX e use-o como fallback de identificação no callback
Não confie apenas no id para cobranças antigas — se migrou de uma integração anterior, use txid como identificador auxiliar