Webhooks & Eventos - AbacatePay

Comandos para escutar, simular e depurar webhooks durante o desenvolvimento.

`abacatepay listen`

Escuta webhooks em tempo real e os encaminha para sua aplicação local.

abacatepay listen [flags]

Flag	Alias	Descrição	Padrão
`--forward-to`	-	URL para onde os eventos serão encaminhados	`http://localhost:3000/webhooks/abacatepay`
`--mock`	-	Simula webhooks sem conectar à API	`false`

O comando listen mantém uma conexão WebSocket ativa com a AbacatePay para receber eventos em tempo real. Todos os eventos recebidos são salvos no log local.Se você não especificar --forward-to, a CLI perguntará via prompt qual URL usar.

Exemplos:

# Escutar e encaminhar para o endpoint padrão
abacatepay listen

# Encaminhar para URL personalizada
abacatepay listen --forward-to http://localhost:8080/webhook

# Modo simulação (sem conexão com a API)
abacatepay listen --mock

Use Ctrl+C para interromper. Todos os eventos ficam salvos e podem ser consultados com abacatepay logs list.

`abacatepay trigger`

Dispara eventos de teste para simular webhooks durante o desenvolvimento.

abacatepay trigger <event>

Eventos disponíveis:

Evento	Descrição
`billing.paid`	Simula o pagamento de uma cobrança Pix
`payout.done`	Simula um saque concluído com sucesso
`payout.failed`	Simula uma falha em saque

O evento billing.paid cria uma cobrança Pix real na API (em modo teste) e simula seu pagamento. Os eventos payout.* geram apenas payloads mock locais.

abacatepay trigger billing.paid

╭────────────────────────────────────────────────────────────────╮
│                                                                │
│  🥑 Billing.paid Triggered                                     │
│                                                                │
│  Charge ID: pix_abc123xyz                                      │
│  Status:    Simulated                                          │
│  Note:      Check your 'listen' terminal for the webhook event │
│                                                                │
╰────────────────────────────────────────────────────────────────╯

{
  "event": "billing.paid",
  "chargeId": "pix_abc123xyz"
}

Execute abacatepay listen em outro terminal antes de usar trigger para receber os webhooks.

`abacatepay events sample`

Gera um payload JSON de exemplo para um tipo de evento específico.

abacatepay events sample <event>

Eventos: billing.paid, payout.done, payout.failed

# Gerar sample de billing.paid
abacatepay events sample billing.paid

# Salvar em arquivo
abacatepay events sample billing.paid > payload.json

{
  "id": "evt_abc123",
  "event": "billing.paid",
  "devMode": true,
  "data": {
    "payment": {
      "amount": 1000,
      "fee": 0,
      "method": "PIX"
    },
    "billing": {
      "id": "bill_xyz789",
      "externalId": "uuid-v4-example",
      "url": "https://abacatepay.com/pay/...",
      "amount": 1000,
      "status": "PAID"
    }
  }
}

{
  "id": "evt_def456",
  "event": "payout.done",
  "devMode": true,
  "data": {
    "transaction": {
      "id": "txn_abc123",
      "status": "COMPLETE",
      "devMode": true,
      "receiptUrl": "https://abacatepay.com/receipt/...",
      "kind": "WITHDRAW",
      "amount": 5000,
      "platformFee": 0,
      "externalId": "uuid-v4-example",
      "createdAt": "2026-01-21T10:30:00Z",
      "updatedAt": "2026-01-21T10:30:00Z"
    }
  }
}

{
  "id": "evt_ghi789",
  "event": "payout.failed",
  "devMode": true,
  "data": {
    "transaction": {
      "id": "txn_xyz456",
      "status": "CANCELLED",
      "kind": "WITHDRAW",
      "amount": 3000,
      "platformFee": 0,
    }
  }
}

Use este comando para entender a estrutura dos payloads e configurar corretamente o parsing na sua aplicação.

`abacatepay events resend`

Reenvia um evento passado para seu endpoint de webhook local.

abacatepay events resend <event-id> [flags]

Flag	Alias	Descrição	Padrão
`--forward-to`	-	URL para onde o evento será reenviado	URL original ou `http://localhost:3000/webhooks/abacatepay`

O evento é buscado no arquivo de log local. O ID pode ser obtido através de abacatepay logs list.

abacatepay events resend evt_abc123xyz

Webhook signing secret: whsec_abacate_local_dev_secret
Resending event evt_abc123xyz to http://localhost:3000/webhooks/abacatepay...

→ [200 OK] billing.paid

╭───────────────────────────────╮
│                               │
│  🥑 Event resent successfully │
│                               │
│  ID:       evt_abc123xyz      │
│  Status:   200 OK             │
│  Duration: 45ms               │
│                               │
╰───────────────────────────────╯

{
  "id": "evt_abc123xyz",
  "status": 200,
  "statusText": "OK",
  "duration": "45ms"
}

O header X-Abacate-Signature é gerado automaticamente com assinatura válida para ambiente de desenvolvimento.

`abacatepay logs list`

Lista o histórico de eventos de webhook gravados localmente.

abacatepay logs list [flags]

Flag	Alias	Descrição	Padrão
`--limit`	`-n`	Número de entradas a exibir	`50`
`--type`	`-t`	Filtrar por tipo de log	-

Tipos de log disponíveis:

Tipo	Descrição
`webhook_received`	Webhook recebido da API
`webhook_forwarded`	Webhook encaminhado com sucesso
`webhook_forward_failed`	Falha ao encaminhar (erro HTTP)
`webhook_forward_error`	Erro de conexão ao encaminhar

# Listar últimos 50 logs
abacatepay logs list

# Listar últimos 10 logs
abacatepay logs list -n 10

# Filtrar apenas webhooks recebidos
abacatepay logs list -t webhook_received

┌─────────────────────────┬─────────────────────────┬───────────────┬────────────────────────────────────┐
│ Timestamp               │ Type                    │ ID            │ URL                                │
├─────────────────────────┼─────────────────────────┼───────────────┼────────────────────────────────────┤
│ 2026-01-21T10:30:00Z    │ webhook_forwarded [200] │ evt_abc123    │ http://localhost:3000/webhooks/abacatepay │
│ 2026-01-21T10:29:55Z    │ webhook_received        │ evt_abc123    │ http://localhost:3000/webhooks/abacatepay │
└─────────────────────────┴─────────────────────────┴───────────────┴────────────────────────────────────┘

{
  "logs": [
    {
      "timestamp": "2026-01-21T10:30:00Z",
      "msg": "webhook_forwarded",
      "id": "evt_abc123",
      "url": "http://localhost:3000/webhooks/abacatepay",
      "statusCode": 200,
      "size_bytes": 1024,
      "raw_message": "{\"id\":\"evt_abc123\",\"event\":\"billing.paid\",...}",
      "event": "billing.paid",
      "level": "INFO"
    }
  ],
  "count": 1
}

`abacatepay logs tail`

Exibe eventos de webhook em tempo real via streaming.

abacatepay logs tail

Este comando conecta ao WebSocket e exibe os eventos conforme chegam, sem encaminhá-los para nenhum endpoint.

Streaming webhook events...

Press Ctrl+C to stop

[2026-01-21T10:30:00Z] billing.paid - evt_abc123xyz
  Amount: R$ 10,00
  Status: paid

^C
Listener stopped

Use logs tail para monitorar eventos sem processá-los. Para receber e encaminhar webhooks, use abacatepay listen.

​abacatepay listen

​abacatepay trigger

​abacatepay events sample

​abacatepay events resend

​abacatepay logs list

​abacatepay logs tail

`abacatepay listen`

`abacatepay trigger`

`abacatepay events sample`

`abacatepay events resend`

`abacatepay logs list`

`abacatepay logs tail`