Webhooks & Notificações em Tempo Real - Kavro Pay

Assim que o cliente paga o PIX no banco dele, nosso servidor envia uma requisição HTTP POST para a sua notification_url com o payload abaixo:

{
  "event": "charge.paid",
  "timestamp": "2026-08-26T12:05:12.000Z",
  "data": {
    "id": "PAY9B1DEB4D3B7D4BAD9BDD2B",
    "status": "paid",
    "amount": 49.00,
    "fee": 0.99,
    "net": 48.01,
    "externalId": "ped_998811",
    "paid_at": "2026-08-26T12:05:12.000Z",
    "end_to_end_id": "E9274656202608261205abcdef",
    "customer": {
      "name": "Carlos Eduardo Silva",
      "document": "12345678909",
      "email": "carlos@email.com.br",
      "phone": "11987654321"
    },
    "metadata": {
      "order_id": "ped_998811",
      "utm_source": "google_ads"
    }
  }
}

Boas Práticas ao Receber Webhooks

Retorne sempre o status HTTP 200 OK de imediato para acusar o recebimento com sucesso.

Caso seu endpoint retorne erro 5xx ou 4xx, o sistema da KavroPay tentará reenviar automaticamente com retentativas exponenciais.
Trate o externalId ou id de forma idempotente para não liberar o produto duas vezes.

Anterior: Consulta de Saldo

Próximo: Idempotência & Rede