Skip to main content

Como funciona

Você cadastra uma URL. Quando um evento acontece, o V4 Pay faz um POST nela com um JSON e uma assinatura. Você confere a assinatura, processa, e responde 2xx.
1

Cadastre o endpoint

A resposta traz um secret. É com ele que a assinatura é calculada — guarde.Dois campos opcionais: events (lista dos eventos que este endpoint quer receber — sem ela, recebe todos; o evento test passa sempre; GET /webhook-endpoints/eventos lista os nomes válidos) e secret (se você preferir gerar o seu, no formato exato whsec_ + 32 hexadecimais).
2

Dispare um evento de teste

POST /webhook-endpoints/{id}/test manda um evento test para essa URL. Serve para conferir que o seu servidor recebe e valida antes de haver dinheiro envolvido.
3

Responda rápido

Responda 200 assim que tiver gravado o evento. Processe o resto depois. O V4 Pay espera até 8 segundos.

O envelope

Todo evento chega neste formato:
Com dois headers:

Eventos

Uma cobrança acabou de ser criada e está pending — pelo POST /pix, pelo checkout de um link de pagamento, pelo cron de assinatura ou pelo POST /charges. É o evento para uma automação entregar o QR ao cliente (WhatsApp, e-mail) assim que ele existe. qr_code_url é a imagem em base64; checkout_url é a página onde o cliente paga.

Validar a assinatura

Calcule o HMAC-SHA256 do corpo exatamente como chegou (bytes brutos, antes de qualquer parse) com o secret do endpoint, e compare com o header em tempo constante.

Reentrega e idempotência

Hoje o V4 Pay faz uma única tentativa por endpoint, com timeout de 8 segundos. Se o seu servidor estiver fora do ar naquele instante, o evento não é reenviado. Trate isso como fato: mantenha GET /pix/status?txid=… como rede de segurança para reconciliar.
Se você tiver mais de um endpoint cadastrado, cada um recebe o evento — e o mesmo txid pode chegar mais de uma vez ao longo do tempo (um subscription.charged seguido de um charge.paid, por exemplo). Use event + data.txid como chave de idempotência do seu lado.

Gerenciar endpoints