Referência - 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.

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

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

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

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

Resposta:

{
  "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	`POST /webhooks`
Listar endpoints	`GET /webhooks`
Obter endpoint	`GET /webhooks/{id}`
Listar entregas	`GET /webhooks/{id}/deliveries`
Remover endpoint	`DELETE /webhooks/{id}`

Quer cadastrar um endpoint de teste rapidamente? Use serviços como webhook.site para receber e inspecionar os payloads sem precisar subir um servidor.

⌘I