> ## 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 (API v1)

> Eventos e payloads de webhooks da API v1 da AbacatePay.

<Warning>
  Estes webhooks são referentes à **API v1**. Para a versão atual (v2), selecione
  a opção **v2** no seletor de versão no topo da documentação e use a página
  principal de Webhooks.
</Warning>

Pense nos webhooks como **“mensagens enviadas pela AbacatePay para o seu
sistema”**, sem que você precise ficar consultando a API o tempo todo.

Na v1 eles seguem os mesmos princípios:

* Você cadastra uma URL no dashboard
* A AbacatePay dispara requisições `POST` para essa URL sempre que algo
  importante acontece
* Seu backend processa o evento e responde com `200 OK` quando tudo estiver certo

## Estrutura geral do payload v1

Na v1, o formato geral do payload segue a mesma ideia da v2, mas sem o campo
`apiVersion`:

```json theme={null}
{
  "event": "billing.paid",
  "devMode": false,
  "data": {
    "id": "bill_123456",
    "amount": 10000,
    "status": "PAID",
    "customer": {
      "id": "cust_123",
      "email": "customer@example.com"
    }
  }
}
```

Os campos mais importantes são:

* **`event`**: nome do evento disparado
* **`devMode`**: indica se o evento veio de ambiente de testes
* **`data`**: objeto com os detalhes do recurso afetado (cobrança, pagamento,
  assinatura, etc.)

## Segurança dos webhooks (v1)

Na v1 você pode (e deve) aplicar as mesmas recomendações da v2:

* Usar um **secret** na URL do webhook
* Validar uma assinatura **HMAC** no header (quando disponível)
* Processar cada evento de forma **idempotente**

Um fluxo típico:

1. Sua URL de webhook é algo como\
   `https://meusite.com/webhooks/abacatepay?webhookSecret=SEU_SECRET`
2. No backend, você confere o `webhookSecret` da query string
3. Em seguida, valida a assinatura HMAC do corpo (caso esteja habilitada)
4. Só depois disso você processa o evento e responde com `200 OK`

## Eventos comuns na v1

A nomenclatura e a granularidade dos eventos na v1 podem ser um pouco diferentes.
Os exemplos abaixo ilustram os tipos mais típicos que você vai encontrar:

| Evento                  | Quando é disparado                           |
| ----------------------- | -------------------------------------------- |
| `billing.created`       | Quando uma cobrança/checkout é criada        |
| `billing.paid`          | Quando um pagamento é concluído com sucesso  |
| `billing.refunded`      | Quando um pagamento é totalmente reembolsado |
| `billing.failed`        | Quando uma tentativa de pagamento falha      |
| `subscription.created`  | Quando uma assinatura é criada               |
| `subscription.canceled` | Quando uma assinatura é cancelada            |

> A lista exata de eventos pode variar conforme a época em que sua integração
> foi feita. Use estes nomes como referência e adapte para os eventos que você
> já recebe hoje no seu sistema.

## Exemplo de webhook `billing.paid` (v1)

```json theme={null}
{
  "event": "billing.paid",
  "devMode": false,
  "data": {
    "id": "bill_abc123",
    "externalId": "pedido-123",
    "amount": 10000,
    "paidAmount": 10000,
    "status": "PAID",
    "customer": {
      "id": "cust_abc123",
      "email": "customer@example.com"
    },
    "createdAt": "2024-01-01T12:00:00.000Z",
    "updatedAt": "2024-01-01T12:05:00.000Z"
  }
}
```

### Boas práticas para consumir webhooks v1

<Card title="Recomendações para integrações legadas" horizontal>
  * **Não dependa** de validação rígida de schema — mantenha o consumo tolerante a mudanças.
  * Use o campo `event` como chave principal de roteamento interno.
  * Sempre trate o corpo como **append‑only**: novos campos podem ser adicionados sem aviso.
  * Registre logs dos payloads recebidos para facilitar migrações futuras para a v2.
</Card>

Se estiver planejando migrar para a v2, recomendamos:

* Mapear quais eventos v1 você já consome hoje
* Consultar a página de Webhooks v2 para encontrar os equivalentes
* Criar uma camada interna que traduza eventos v1 → v2 enquanto você atualiza sua lógica