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 Seller Dashboard
Quando um evento ocorrer, enviamos uma requisição POST para sua URL com o payload do evento
Valide a assinatura HMAC no header X-Apexpy-Signature
Processe o evento e retorne HTTP 200

Configuração só no painel

Não existe POST /v1/webhooks na API pública. Endereço, eventos e secret ficam em Dashboard → Webhooks. Por cobrança, use callback_url.

Dois modos de notificação

1. Webhook global (dashboard)

Cadastre uma URL no painel. Ela recebe os eventos que você marcar (todas as cobranças e saques da conta).

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:

POST /v1/charges

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

Payload do `callback_url` (PIX)

Quando o pagamento PIX for confirmado, sua URL recebe um JSON enxuto (não o envelope event + data do webhook global):

{
  "id": "ci_k7m2p9xr4nqs",
  "status": "paid",
  "amount": 10000,
  "txid": "E12345678202511281234567890123456"
}

Identificação do pedido via callback_url

O campo id é o identificador da cobrança (ci_...). Guarde o pix.txid na criação e use-o como fallback — o txid é imutável e vem do arranjo PIX.

$pedido = buscarPor('transaction_id', $dados['id']);
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
`charge.expired`	Cobrança PIX expirada
`payout.created`	Saque criado
`payout.completed`	Saque concluído
`payout.failed`	Saque falhou

Boas práticas

Valide a assinatura de todo webhook (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