Pular para o conteúdo principal
Hoje a Pagou expõe três famílias públicas de webhook. Pagamentos e assinaturas usam envelope com event. Transferências usam envelope de payout com type.

​
Comparação de envelopes

DomínioCampo de evento no topoCampo do recursoNome concreto do evento
Pagamentosevent: "transaction"datadata.event_type
Assinaturasevent: "subscription"datadata.event_type
Transferênciastypedata.objecttype no topo

​
Exemplo de webhook de pagamento

{
  "id": "evt_pay_1001",
  "event": "transaction",
  "api_version": "v1",
  "data": {
    "id": "tr_1001",
    "event_type": "transaction.paid",
    "correlation_id": "order_1001",
    "method": "pix",
    "status": "paid",
    "amount": 1500,
    "currency": "BRL"
  }
}

​
Exemplo de webhook de transferência

{
  "id": "evt_payout_1001",
  "type": "payout.transferred",
  "api_version": "v2",
  "data": {
    "object": {
      "id": "po_1001",
      "status": "paid",
      "type": "pix",
      "amount": 1200
    }
  }
}

​
Exemplo de webhook de assinatura

{
  "api_version": "v2",
  "id": "120ebf7cc24835b5ea33ee617bf70cb91c3a4dcd7413afcb05f61c60d1c9de3d",
  "event": "subscription",
  "url": "https://merchant.example/webhooks/pagou",
  "data": {
    "id": "019e5d23-6ec8-73de-9c95-06093c62ba00",
    "event_type": "subscription.created",
    "status": "active",
    "amount": 500,
    "currency": "BRL",
    "latest_transaction": {
      "id": "019e5d23-6ed7-7121-a667-41e5ac929c72",
      "status": "paid"
    }
  }
}

​
Resposta de ACK

{
  "received": true
}

​
Erro comum de ingestão

{
  "error": "missing_event_id"
}
Como corrigir: exija o id de topo, faça deduplicação por esse valor, responda 200 OK rapidamente e processe de forma assíncrona.

​
Guia de mapeamento

  • Dirija o estado de negócio pelo status do recurso, não por suposição no front-end.
  • Roteie mudanças de ciclo de vida de assinatura por data.event_type.
  • Mapeie o evento de transferência payout.transferred para o status liquidado do recurso paid.
  • Reconcilie se seu worker cair depois do ack.

​
Leia a seguir