> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abacatepay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receba webhooks de dev mode e encaminhe para sua aplicação local com a AbacatePay CLI.

***

### `abacatepay listen`

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

```bash theme={null}
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:**

```bash theme={null}
# Encaminhar para uma URL específica
abacatepay listen --forward-to http://localhost:8080/webhook

# Escolher a URL no prompt
abacatepay listen
```

<Warning>
  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`](./payments) ou pela API.
</Warning>

O `listen` precisa de uma sessão ativa — rode [`abacatepay login`](./auth) 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](/pages/webhooks/security#2-assinatura-hmac). A validação que você já implementou seguindo a documentação funciona sem alteração.

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

***

### 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.

```text theme={null}
🥑 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 |

```bash theme={null}
# 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](/pages/webhooks/events/transparent).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.