Gerenciar Webhooks

Todas as rotas de gerenciamento de webhooks requerem autenticação via JWT ou API Key.

Criar webhook

`POST /v1/webhooks/merchant`

Cadastra uma nova URL para receber eventos. Você pode escolher quais eventos quer receber, ou deixar em branco para receber tudo.

POST https://api.liquera.com.br/v1/webhooks/merchant
Authorization: Bearer <jwt_ou_api_key>
Content-Type: application/json

Body

string

required

URL pública que receberá as requisições POST com os eventos. Deve ser HTTPS em produção.

string

Nome identificador do webhook. Máximo de 100 caracteres. Opcional.

array

Lista de eventos que este webhook deve receber. Se vazio ou omitido, recebe todos os eventos (wildcard).Valores aceitos: charge.paid, charge.refunded, withdraw.completed, withdraw.failed, withdraw.refunded, pixkey.updated, infraction.received, infraction.updated, infraction.refund_completed.

Exemplos

Receber apenas pagamentos
Receber todos os eventos

curl -X POST https://api.liquera.com.br/v1/webhooks/merchant \
  -H "Authorization: Bearer lk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meusite.com.br/webhooks/liquera",
    "name": "Checkout Principal",
    "events": ["charge.paid", "charge.refunded"]
  }'

curl -X POST https://api.liquera.com.br/v1/webhooks/merchant \
  -H "Authorization: Bearer lk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meusite.com.br/webhooks/liquera",
    "name": "Logging Geral",
    "events": []
  }'

Response `201`

{
  "webhook": {
    "id": "clx8abc123",
    "name": "Checkout Principal",
    "url": "https://meusite.com.br/webhooks/liquera",
    "events": ["charge.paid", "charge.refunded"],
    "secret": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef12345678",
    "status": "ACTIVE",
    "createdAt": "2025-01-15T10:00:00.000Z"
  }
}

O campo secret é retornado apenas na criação. Guarde-o imediatamente — ele é enviado no header x-webhook-secret de cada entrega e você precisa dele para verificar que os eventos são legítimos. Se perder o secret, remova o webhook e crie um novo.

Listar webhooks

`GET /v1/webhooks/merchant`

Retorna todos os webhooks cadastrados, incluindo os últimos 20 logs de entrega de cada um.

GET https://api.liquera.com.br/v1/webhooks/merchant
Authorization: Bearer <jwt_ou_api_key>

curl https://api.liquera.com.br/v1/webhooks/merchant \
  -H "Authorization: Bearer lk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response `200`

{
  "webhooks": [
    {
      "id": "clx8abc123",
      "name": "Checkout Principal",
      "url": "https://meusite.com.br/webhooks/liquera",
      "events": ["charge.paid", "charge.refunded"],
      "secret": "wh_****5678",
      "status": "ACTIVE",
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": "2025-01-15T10:00:00.000Z",
      "logs": [
        {
          "id": "log_001",
          "deliveryId": "dlv_abc",
          "event": "charge.paid",
          "url": "https://meusite.com.br/webhooks/liquera",
          "payload": "{\"event\":\"charge.paid\",\"data\":{...}}",
          "statusCode": 200,
          "response": "{\"received\":true}",
          "attempts": 1,
          "success": true,
          "createdAt": "2025-01-15T14:22:05.000Z"
        }
      ]
    }
  ]
}

O campo secret na listagem é mascarado (ex: wh_****5678). Para recuperar o secret completo, é necessário deletar e recriar o webhook.

Atualizar webhook

`PATCH /v1/webhooks/merchant/:id`

Atualiza um ou mais campos de um webhook existente. Envie apenas os campos que deseja alterar.

PATCH https://api.liquera.com.br/v1/webhooks/merchant/:id
Authorization: Bearer <jwt_ou_api_key>
Content-Type: application/json

Path parameters

string

required

ID do webhook a ser atualizado.

Body (todos opcionais)

string

Nova URL de destino.

string | null

Novo nome. Envie null para remover o nome.

array

Nova lista de eventos. Use [] para voltar ao modo wildcard (todos os eventos).

string

"ACTIVE" para reativar ou "INACTIVE" para pausar as entregas sem deletar o webhook.

Exemplos

Pausar webhook
Adicionar eventos
Mudar URL

curl -X PATCH https://api.liquera.com.br/v1/webhooks/merchant/clx8abc123 \
  -H "Authorization: Bearer lk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "status": "INACTIVE" }'

curl -X PATCH https://api.liquera.com.br/v1/webhooks/merchant/clx8abc123 \
  -H "Authorization: Bearer lk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["charge.paid", "charge.refunded", "withdraw.completed", "withdraw.failed"]
  }'

curl -X PATCH https://api.liquera.com.br/v1/webhooks/merchant/clx8abc123 \
  -H "Authorization: Bearer lk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://api.novodominio.com.br/webhooks" }'

Response `200`

{
  "webhook": {
    "id": "clx8abc123",
    "name": "Checkout Principal",
    "url": "https://meusite.com.br/webhooks/liquera",
    "events": ["charge.paid", "charge.refunded", "withdraw.completed", "withdraw.failed"],
    "status": "ACTIVE",
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T16:00:00.000Z"
  }
}

Remover webhook

`DELETE /v1/webhooks/merchant/:id`

Remove um webhook. As entregas para essa URL cessam imediatamente.

DELETE https://api.liquera.com.br/v1/webhooks/merchant/:id
Authorization: Bearer <jwt_ou_api_key>

curl -X DELETE https://api.liquera.com.br/v1/webhooks/merchant/clx8abc123 \
  -H "Authorization: Bearer lk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response `200`

{
  "message": "Webhook removido com sucesso"
}

Listar eventos disponíveis

`GET /v1/webhooks/merchant/events`

Retorna a lista completa de eventos disponíveis para inscrição. Útil para descoberta dinâmica.

curl https://api.liquera.com.br/v1/webhooks/merchant/events \
  -H "Authorization: Bearer lk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response `200`

{
  "events": [
    { "event": "charge.paid",               "description": "Cobrança PIX paga pelo cliente",       "category": "Cobranças"  },
    { "event": "charge.refunded",            "description": "Cobrança PIX estornada",               "category": "Cobranças"  },
    { "event": "withdraw.completed",         "description": "Saque concluído com sucesso",          "category": "Saques"     },
    { "event": "withdraw.failed",            "description": "Saque falhou ou foi devolvido",        "category": "Saques"     },
    { "event": "withdraw.refunded",          "description": "Saque devolvido (refund de transferência)", "category": "Saques" },
    { "event": "pixkey.updated",             "description": "Chave PIX atualizada",                "category": "Chave PIX"  },
    { "event": "infraction.received",        "description": "Nova infração PIX (MED) recebida",    "category": "Infrações"  },
    { "event": "infraction.updated",         "description": "Infração PIX atualizada",             "category": "Infrações"  },
    { "event": "infraction.refund_completed","description": "Reembolso de infração concluído",     "category": "Infrações"  }
  ]
}

Comece Aqui

Autenticação

Webhooks

Gerenciar Webhooks

Criar webhook

`POST /v1/webhooks/merchant`

Body

Exemplos

Response `201`

Listar webhooks

`GET /v1/webhooks/merchant`

Response `200`

Atualizar webhook

`PATCH /v1/webhooks/merchant/:id`

Path parameters

Body (todos opcionais)

Exemplos

Response `200`

Remover webhook

`DELETE /v1/webhooks/merchant/:id`

Response `200`

Listar eventos disponíveis

`GET /v1/webhooks/merchant/events`

Response `200`

​Criar webhook

​POST /v1/webhooks/merchant

​Body

​Exemplos

​Response 201

​Listar webhooks

​GET /v1/webhooks/merchant

​Response 200

​Atualizar webhook

​PATCH /v1/webhooks/merchant/:id

​Path parameters

​Body (todos opcionais)

​Exemplos

​Response 200

​Remover webhook

​DELETE /v1/webhooks/merchant/:id

​Response 200

​Listar eventos disponíveis

​GET /v1/webhooks/merchant/events

​Response 200

Criar webhook

`POST /v1/webhooks/merchant`

Body

Exemplos

Response `201`

Listar webhooks

`GET /v1/webhooks/merchant`

Response `200`

Atualizar webhook

`PATCH /v1/webhooks/merchant/:id`

Path parameters

Body (todos opcionais)

Exemplos

Response `200`

Remover webhook

`DELETE /v1/webhooks/merchant/:id`

Response `200`

Listar eventos disponíveis

`GET /v1/webhooks/merchant/events`

Response `200`