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

# Referência

> Endpoints para gerenciar URLs que recebem eventos da Liquerapay.

Esta seção cobre as **rotas de gerenciamento** dos endpoints de webhook
(criar, listar, consultar, remover, inspecionar entregas). Para entender o
**payload** dos eventos e como validar a assinatura, veja o
[guia de Webhooks](/pages/start/webhooks).

## Conceito

Um **endpoint de webhook** é uma URL HTTPS pública do seu backend
cadastrada para receber eventos. Cada endpoint tem:

* Uma **URL** (única dentro do seu merchant)
* Uma lista de **`events`** — os eventos aos quais ele está inscrito (1 a 8)
* Um `secret` — a **chave de assinatura** HMAC usada para assinar as requisições
* Um flag **active**, que fica `false` automaticamente se o endpoint acumular
  muitas falhas de entrega

<Warning>
  O `secret` é mostrado **uma única vez**, na resposta do `POST`.
  Salve em local seguro — se você perdê-lo, será necessário remover
  o endpoint e cadastrar um novo (o que gera um `secret` novo).
</Warning>

## Eventos disponíveis

| Evento                 | Quando                                                           |
| ---------------------- | ---------------------------------------------------------------- |
| `CHARGE_PAID`          | Cobrança PIX (Checkout Transparente) foi paga                    |
| `REFUND_COMPLETED`     | Devolução confirmada pelo PSP                                    |
| `REFUND_FAILED`        | Devolução falhou                                                 |
| `WITHDRAWAL_COMPLETED` | Saque foi concluído                                              |
| `WITHDRAWAL_FAILED`    | Saque falhou ou foi devolvido                                    |
| `CHECKOUT_PAID`        | Cobrança de Checkout Hospedado / link de pagamento foi paga      |
| `CHECKOUT_REFUNDED`    | Cobrança de Checkout Hospedado / link de pagamento foi devolvida |
| `CHARGE_EXPIRED`       | Reservado — ainda não disparado hoje                             |

## Exemplo: criar endpoint

```bash theme={null}
POST /webhooks
{
  "url": "https://meusite.com/webhooks/liquerapay",
  "events": ["CHARGE_PAID", "REFUND_COMPLETED", "REFUND_FAILED"]
}
```

**Resposta:**

```json theme={null}
{
  "data": {
    "id": "whk_018fa3b56c7d7e30a8b9",
    "url": "https://meusite.com/webhooks/liquerapay",
    "events": ["CHARGE_PAID", "REFUND_COMPLETED", "REFUND_FAILED"],
    "secret": "7f3c1d8b2a5e9f0c1d8b2a5e9f0c1d8b2a5e9f0c1d8b2a5e9f0c1d8b2a5e9f0c",
    "active": true,
    "createdAt": "2026-04-19T18:00:00.000Z"
  },
  "error": null,
  "success": true
}
```

## Operações disponíveis

| Operação                                      | Endpoint                        |
| --------------------------------------------- | ------------------------------- |
| [Criar endpoint](/pages/webhooks/create)      | `POST /webhooks`                |
| [Listar endpoints](/pages/webhooks/list)      | `GET /webhooks`                 |
| [Obter endpoint](/pages/webhooks/get)         | `GET /webhooks/{id}`            |
| [Listar entregas](/pages/webhooks/deliveries) | `GET /webhooks/{id}/deliveries` |
| [Remover endpoint](/pages/webhooks/delete)    | `DELETE /webhooks/{id}`         |

<Tip>
  Quer cadastrar um endpoint de teste rapidamente? Use serviços como
  [webhook.site](https://webhook.site) para receber e inspecionar
  os payloads sem precisar subir um servidor.
</Tip>