Webhooks

A PagLemon envia eventos (ex.: pagamento aprovado) para uma URL sua via POST. É assim que seu sistema sabe, em tempo real, que uma cobrança foi paga.

Registrar um endpoint

No painel, cadastre um webhook informando:

• name — um nome pra identificar.
• url — o endereço que vai receber os eventos (POST, JSON).
• events — lista de eventos que quer receber (vazio = todos).
• paymentLinkIds (opcional) — receber só de links específicos.

Formato do evento

O corpo é sempre:

{
  "event": "payment.approved",
  "timestamp": "2026-07-08T23:59:00.000Z",
  "data": {
    "id": "pay_abc123",
    "externalId": "gtw_xyz",
    "amount": 1990,
    "status": "FINISHED",
    "paymentLinkId": "link-abcd",
    "customerEmail": "[email protected]",
    "customerName": "Maria Silva",
    "confirmedAt": "2026-07-08T23:59:00.000Z",
    "metadata": null
  }
}

• amount vem em centavos.
• status é o status interno do pagamento (FINISHED = pago).

Eventos disponíveis

Pagamentos: payment.approved · payment.pending · payment.cancelled · payment.refunded · payment.failed · payment.blocked

Disputas: dispute.created · dispute.won · dispute.lost

Saques: withdrawal.completed · withdrawal.rejected · withdrawal.failed · withdrawal.blocked

O saque tem um bloco data próprio (id, amount, status, pixKey, requestedAt, completedAt).

Boas práticas do receptor

• Responda HTTP 2xx rápido (timeout de 10s). Faça o processamento pesado de forma assíncrona.
• Trate o recebimento como idempotente (o mesmo evento pode chegar mais de uma vez).

⚠️ Verificação de assinatura (importante)

Hoje os webhooks NÃO são assinados (não há HMAC nem segredo). O único header distintivo é User-Agent: Marketplace-Webhook/1.0.

Isso significa que, no momento, você não consegue provar criptograficamente que o evento veio da PagLemon. Até a assinatura por HMAC ser lançada, recomendamos:

• usar um endpoint com URL secreta/difícil de adivinhar;
• confirmar o pagamento por um canal confiável antes de liberar entrega de alto valor;
• restringir a origem por IP, se possível.

A assinatura por HMAC + segredo por webhook está no roadmap.

Também não há retry automático na entrega ao vivo — você pode reenviar um evento manualmente pelos logs de webhook no painel.