Endpoints da API
Webhooks
Existem duas formas de receber eventos da Pix Processamento:
callbackUrlna transação, você informa a URL a cadaPOST /pix,POST /withdrawouPOST /internal-transfer. Simples, sem cadastro, sem assinatura.- Webhook cadastrado (esta seção), você registra a URL uma vez, escolhe quais eventos quer receber e ganha assinatura HMAC no header. É o caminho recomendado.
As duas convivem: se a transação tem callbackUrl e a conta tem webhooks ativos, os dois recebem.
POSTCriar webhookGETListar webhooksGETDetalhar webhookPATCHAtualizar webhookDELETERemover webhookPOSTRotacionar secretGETContar disparosGETDetalhe do disparo
Quando usar cada um
| Pergunta | Endpoint |
|---|---|
| Quero registrar minha URL e receber eventos | POST /user/webhooks |
| Quais webhooks estão cadastrados na minha conta? | GET /user/webhooks |
| Esse webhook está ativo? Quais eventos ele assina? | GET /user/webhooks/{id} |
| Quero trocar a URL, pausar ou mudar os eventos | PATCH /user/webhooks/{id} |
| Quero desativar de vez | DELETE /user/webhooks/{id} |
| Vazou o secret, preciso de um novo | POST /user/webhooks/{id}/rotate-secret |
| Quantos disparos já saíram? | GET /user/webhooks/sent/quantity |
| O que exatamente foi enviado nesse disparo e o que respondi? | GET /user/webhooks/{id}/sent/{callbackId} |
| Meu endpoint ficou fora, quero reenviar o que falhou | POST /user/callbacks/resend/webhook/{webhookId} |
O secret aparece uma única vez, na resposta de POST /user/webhooks (com generateSecret: true) e na de POST /user/webhooks/{id}/rotate-secret. Não há endpoint para lê-lo depois. Se perder, rotacione.
Limite de 5 webhooks ativos por conta. Criar ou reativar acima disso devolve 409 Conflict. Webhooks inativos não contam.
Eventos assináveis
Enviar events: [] (ou omitir o campo) assina todos os eventos.
| Evento | Quando dispara |
|---|---|
TRANSACTION_PENDING | Transação criada e aguardando pagamento |
TRANSACTION_COMPLETED | Transação liquidada |
TRANSACTION_CANCELED | Transação cancelada |
TRANSACTION_WAITING_FOR_REFUND | Estorno solicitado, aguardando processamento |
TRANSACTION_REFUNDED | Estorno concluído |
TRANSACTION_EXPIRED | Cobrança expirou sem pagamento |
TRANSACTION_ERROR | Transação terminou em erro |
TRANSACTION_SUSPECTED_FRAUD | Transação marcada como suspeita de fraude |
TRANSACTION_SUSPECTED_FRAUD_REVERSAL | Marcação de suspeita de fraude revertida |
INFRACTION_CHANGED | Infração (MED) ligada a uma transação mudou de status |
O evento do disparo vai no header X-Callback-Event. Veja o payload completo e a verificação da assinatura em Webhooks.