📡 Webhooks — LumoPay API

A LumoPay envia notificações automáticas (webhooks) para a URL configurada na sua conta sempre que o status de uma transação for atualizado.

🔐 Autenticação e Validação

Todos os webhooks enviados pela LumoPay incluem o header X-Signature com uma assinatura HMAC-SHA256 gerada a partir do payload completo e do seu api_secret.

Headers enviados pela LumoPay

Header	Descrição
`Content-Type`	`application/json`
`X-Webhook-Event`	Tipo do evento (ex: `payment.paid`)
`X-Signature`	Assinatura HMAC-SHA256 do payload

Validando a assinatura

Importante: A assinatura é gerada sobre o envelope completo (incluindo os campos event, data e timestamp).

📦 Estrutura do Envelope

Todos os webhooks chegam no seguinte formato:

{
  "event": "payment.paid",
  "data": { ... },
  "timestamp": "2026-06-08T00:00:16.000Z"
}

Campo	Tipo	Descrição
`event`	`string`	Tipo do evento
`data`	`object`	Dados da transação
`timestamp`	`string` (ISO 8601)	Data/hora do envio

✅ Como responder a um webhook

Responda sempre com HTTP 200 para confirmar o recebimento. Qualquer outro status pode acionar reenvios automáticos.

HTTP/1.1 200 OK
Content-Type: application/json

{ "received": true }

📋 Exemplo completo de envio

POST https://seusite.com/webhook
Content-Type: application/json
X-Webhook-Event: payment.paid
X-Signature: a3f1b2c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2

{
  "event": "payment.paid",
  "data": {
    "event": "payment.paid",
    "transaction_id": "cm1a2b3c4d5e6f7g8h9i0j",
    "external_id": "EXT-DEP-12345",
    "type": "pix_in",
    "amount": 150.00,
    "amount_fees": 2.50,
    "net_amount": 147.50,
    "status": "paid",
    "end_to_end_id": "E60701190202606080000DY5OHJK3BDX",
    "customer": {
      "name": "LUMOPAY BRASIL LTDA",
      "document": "12345678900"
    },
    "paidAt": "2026-06-08T00:00:16.000Z",
    "createdAt": "2026-06-07T23:59:09.000Z",
    "updatedAt": "2026-06-08T00:00:16.000Z"
  },
  "timestamp": "2026-06-08T00:00:16.568Z"
}

Introdução Webhooks

📡 Webhooks — LumoPay API#

🔐 Autenticação e Validação#

Headers enviados pela LumoPay#

Validando a assinatura#

📦 Estrutura do Envelope#

✅ Como responder a um webhook#