Webhooks - AbacatePay

`abacatepay listen`

Recebe em tempo real os webhooks da sua conta em dev mode e encaminha cada um para uma URL local.

abacatepay listen [flags]

Flag	Descrição	Padrão
`--forward-to`	URL que vai receber os eventos (`http://` ou `https://`)	pergunta no terminal, sugerindo `http://localhost:3000/webhooks/abacatepay`

Exemplos:

# Encaminhar para uma URL específica
abacatepay listen --forward-to http://localhost:8080/webhook

# Escolher a URL no prompt
abacatepay listen

A CLI só recebe eventos de dev mode. Eventos de produção nunca chegam no listen. Para testar, use uma API key de dev mode e gere eventos com payments simulate ou pela API.

O listen precisa de uma sessão ativa — rode abacatepay login antes.

Assinatura dos eventos encaminhados

Cada evento é encaminhado como POST com Content-Type: application/json e o header de assinatura que a AbacatePay usa em produção:

X-Webhook-Signature: <assinatura em base64>

A assinatura é HMAC-SHA256 do corpo raw com a mesma chave pública documentada em Segurança de Webhooks. A validação que você já implementou seguindo a documentação funciona sem alteração.

O secret na URL (?webhookSecret=...) não é adicionado pela CLI. Se sua rota exige esse parâmetro, inclua-o no --forward-to.

Painel interativo

Em um terminal interativo, o listen abre um painel que mostra o status da conexão e a lista de eventos recebidos, com o status HTTP que sua aplicação devolveu.

🥑 abacatepay listen
● connected  forwarding to http://localhost:3000/webhooks/abacatepay

14:32:07  --> transparent.completed [char_xyz789]
14:32:07  <-- [200] transparent.completed

↑/k up • ↓/j down • G latest • q quit

Cada evento gera duas linhas: --> quando chega da AbacatePay, com o ID do recurso (cobrança, checkout, assinatura etc.), e <-- com o status HTTP que sua aplicação devolveu (verde para 2xx, vermelho para o resto). O painel guarda os últimos 500 eventos.

Tecla	Ação
`↑` / `k`	Rola para cima
`↓` / `j`	Rola para baixo
`G` / `End`	Vai para o evento mais recente
`q` / `Esc` / `Ctrl+C`	Encerra

Com -v, o painel também mostra o JSON de cada evento. Quando a saída não é um terminal (pipe, CI), o listen imprime uma linha por evento recebido e por encaminhamento, sem painel (com -v, também o JSON do evento). As mensagens de status vão para o stderr.

Reconexão

Se a conexão cair, a CLI tenta reconectar sozinha, com espera crescente entre as tentativas (de 1s até 15s), por até 5 tentativas seguidas.

Histórico local

Todos os eventos recebidos e o resultado de cada encaminhamento ficam em ~/.abacatepay/logs/transactions.log, uma linha JSON por registro:

`msg`	Quando
`webhook_received`	Evento recebido da AbacatePay (inclui o payload em `raw_message`)
`webhook_forwarded`	Sua aplicação respondeu com status `2xx`
`webhook_forward_error`	Sua aplicação respondeu com status fora de `2xx` (inclui `response_body`)
`webhook_forward_failed`	Não foi possível conectar na URL de destino

# Encaminhamentos que falharam
jq 'select(.msg=="webhook_forward_error" or .msg=="webhook_forward_failed")' ~/.abacatepay/logs/transactions.log

# Payload do último evento recebido
jq -r 'select(.msg=="webhook_received") | .raw_message' ~/.abacatepay/logs/transactions.log | tail -1 | jq

Veja os eventos possíveis e seus payloads em Eventos de Webhook.

​abacatepay listen

​Assinatura dos eventos encaminhados

​Painel interativo

​Reconexão

​Histórico local

`abacatepay listen`

Assinatura dos eventos encaminhados

Painel interativo

Reconexão

Histórico local