Webhooks

Receba eventos da Liquerapay no seu backend em tempo real.

Webhooks são mensagens HTTP POST que a Liquerapay envia para uma URL sua sempre que algo importante acontece (cobrança paga, saque concluído, etc.). É a forma recomendada de manter seu sistema sincronizado — muito mais eficiente do que fazer polling.

Fluxo geral

1. Você cadastra uma URL HTTPS e escolhe os eventos

   Use POST /webhooks ou cadastre pelo painel, informando quais eventos (events) você quer receber. Nós te devolvemos um secret — a chave de assinatura.

2. Acontece um evento

   Por exemplo: o cliente paga uma cobrança PIX.

3. Disparamos um POST

   Enviamos uma requisição POST para a sua URL com o payload do evento e o header de assinatura.

4. Você responde 2xx

   Seu backend valida a assinatura, processa o evento e responde com HTTP 2xx rapidamente. Se responder erro 5xx ou demorar muito (timeout), fazemos retry.

Estrutura do payload

Todo webhook tem o mesmo formato base:

{
  "id": "evt_018fa4c76d8e7f209a1b",
  "event": "CHARGE_PAID",
  "createdAt": "2026-04-19T18:34:55.000Z",
  "data": {
    "chargeId": "chg_018f8e2d9a5f7b10c3d4",
    "amount": 5000,
    "status": "PAID",
    "txid": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f",
    "end2endId": "E12345678202604191834550000000001",
    "paidAt": "2026-04-19T18:34:55.000Z",
    "customer": { "name": "João Silva", "document": "12345678900", "bank": "Nubank" }
  }
}

• id: identificador único desta entrega de evento (evt_...) — use como chave de idempotência
• event: nome do evento, ver tabela abaixo
• createdAt: quando o evento ocorreu
• data: dados específicos do evento

Beta: o shape de data pode ganhar novos campos sem aviso. Trate o payload como append-only e ignore campos/eventos desconhecidos.

Eventos disponíveis

Ao cadastrar um endpoint você escolhe de 1 a 8 eventos em events — o endpoint só recebe os eventos que ele está inscrito, não recebe tudo por padrão.

Evento	Quando é disparado
CHARGE_PAID	Cobrança PIX (Checkout Transparente) foi paga com sucesso
REFUND_COMPLETED	Uma devolução foi confirmada pelo PSP
REFUND_FAILED	Uma devolução falhou
WITHDRAWAL_COMPLETED	Saque foi processado e o PIX enviado
WITHDRAWAL_FAILED	Saque falhou ou foi devolvido
CHECKOUT_PAID	Cobrança de um Checkout Hospedado / link de pagamento foi paga
CHECKOUT_REFUNDED	Cobrança de um Checkout Hospedado / link de pagamento foi devolvida
CHARGE_EXPIRED	Reservado para cobrança expirada — ainda não é disparado hoje, mas já pode ser inscrito

CHECKOUT_PAID e CHECKOUT_REFUNDED pertencem ao Checkout Hospedado (documentação completa em breve). CHARGE_EXPIRED existe no schema mas nenhum job dispara esse evento atualmente — não dependa dele ainda.

Header enviado

Toda requisição POST para a sua URL inclui:

Header	Conteúdo
Content-Type	application/json
User-Agent	Liquera-Webhook/1.0
Liquera-Signature	Assinatura no formato t=<timestamp>,v1=<hmac_hex>

O header de assinatura é Liquera-Signature. Não confunda com X-Webhook-Signature, X-Liquera-Signature ou variações — é exatamente Liquera-Signature.

Validando a assinatura

A chave de assinatura (secret) é devolvida uma única vez, na resposta do POST /webhooks. Guarde-a em variável de ambiente ou cofre — é ela que prova que uma requisição realmente veio da Liquerapay.

O header Liquera-Signature segue o formato t=<timestamp>,v1=<assinatura>:

• t: timestamp Unix (segundos) de quando o evento foi assinado
• v1: HMAC-SHA256, em hex, calculado sobre a string "${t}.${corpo_bruto}" (o timestamp, um ponto, e o corpo bruto da requisição — antes de JSON.parse), usando o secret do endpoint como chave

Para validar: extraia t e v1 do header, recalcule o HMAC da mesma forma e compare com v1 usando uma comparação em tempo constante.

Node.js

import crypto from 'node:crypto'

function verify(req, secret) {
  const header = req.headers['liquera-signature']
  if (!header) return false

  const parts = Object.fromEntries(
    header.split(',').map((p) => p.split('=')),
  )
  const { t: timestamp, v1: signature } = parts
  if (!timestamp || !signature) return false

  const signedPayload = `${timestamp}.${req.rawBody}` // body bruto, string ou Buffer
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  const valid =
    signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))

  // opcional, mas recomendado: rejeitar timestamps muito antigos
  const toleranceSeconds = 300
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= toleranceSeconds

  return valid && fresh
}

Sempre valide a assinatura antes de processar o evento — sem isso, qualquer pessoa pode fazer POST na sua URL e simular eventos. A API não impõe uma janela de tolerância no t; recomendamos rejeitar timestamps com mais de alguns minutos de diferença para evitar replay de requisições antigas.

Política de retry

Quando uma tentativa falha, o comportamento depende do tipo de falha:

• Erro 4xx (ex.: sua URL retorna 400/404): tratamos como rejeição definitiva do seu lado — não tentamos de novo.
• Erro 5xx, timeout ou falha de rede: reagendamos automaticamente com backoff exponencial (base de 2 segundos), até 3 tentativas no total.

Tentativa	Quando
1	Imediata
2	~2 segundos depois, se a 1ª falhar com erro retentável
3	~4 segundos depois, se a 2ª falhar com erro retentável

Timeout de cada request: 10 segundos. Depois da 3ª tentativa, a entrega fica FAILED definitivamente.

Se um endpoint acumular 10 ou mais entregas com falha nas últimas 24h, ele é desativado automaticamente (active: false) e para de receber eventos. Hoje não há uma rota de auto-reativação — se isso acontecer, contate o suporte ou remova o endpoint (DELETE) e cadastre um novo (POST), o que também gera um novo secret.

Use GET /webhooks/{id}/deliveries para inspecionar o histórico de entregas (status HTTP, sucesso, tentativa e erro) de um endpoint e debugar falhas.

Idempotência

Como podemos retentar entregas, o mesmo evento pode chegar mais de uma vez. Implemente idempotência usando o id do topo do payload (evt_...) como chave única.

const alreadyProcessed = await db.webhookEvent.findUnique({
  where: { id: payload.id },
})
if (alreadyProcessed) return reply.status(200).send()

Boas práticas

Recomendações

• Responda rápido (idealmente < 2s) — mova trabalho pesado para fila
• Sempre valide a assinatura Liquera-Signature
• Implemente idempotência pelo id do payload
• Tenha logs de todos os payloads recebidos para debugging
• Use HTTPS com certificado válido
• Não dependa de ordem de entrega — eventos podem chegar fora de ordem