Visão geral de webhooks - Pagou Developer Docs

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ínio	Campo de evento no topo	Campo do recurso	Nome concreto do evento
Pagamentos	`event: "transaction"`	`data`	`data.event_type`
Assinaturas	`event: "subscription"`	`data`	`data.event_type`
Transferências	`type`	`data.object`	`type` no topo

Exemplo de webhook de pagamento

{
  "id": "evt_pay_1001",
  "event": "transaction",
  "api_version": "v1",
  "data": {
    "id": "018f1f2e-7b42-7c9a-8d3e-1a2b3c4d5e6f",
    "event_type": "transaction.paid",
    "correlation_id": "order_1001",
    "method": "pix",
    "status": "paid",
    "amount": 1500,
    "currency": "BRL",
    "informations": [
      { "key": "order_id", "value": "order_1001" }
    ],
    "customer": {
      "name": "Ana Souza",
      "email": "ana@example.com",
      "phone": "+5511999998888"
    },
    "products": [
      {
        "id": "018f1f2e-7b42-7c9a-8d3e-9f0a1b2c3d4e",
        "title": "Curso completo",
        "unit_price": 1500,
        "quantity": 1,
        "tangible": false,
        "kind": "product"
      }
    ],
    "attribution": {
      "utm_source": "instagram",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday",
      "utm_content": null,
      "utm_term": null,
      "fbc": null,
      "fbp": null,
      "gclid": null,
      "ttclid": null,
      "src": null,
      "sck": null,
      "checkout_url": "https://pay.example/checkout/abc",
      "checkout_url_declared": null,
      "referrer_url": "https://instagram.com/"
    }
  }
}

data.informations devolve o array informations que você enviou ao criar a transação via API; só aparece quando você enviou entradas customizadas. Veja Eventos de Pagamento. Os eventos de transação também trazem data.customer (name, email e phone do comprador — nunca o documento), data.products (os itens comprados, na mesma forma do endpoint de detalhe da transação) e data.attribution (UTMs de campanha, click IDs de anúncio, o par de afiliado src/sck, a URL de checkout derivada por nós e a declarada, e a de origem). Todos são opcionais: customer e attribution podem vir null, products pode vir vazio, e o attribution vem sempre null em transações criadas pela API. Veja Eventos de Pagamento.

Exemplo de webhook de transferência

{
  "id": "evt_payout_1001",
  "type": "payout.transferred",
  "api_version": "v2",
  "data": {
    "object": {
      "id": "018f1f2e-7b45-7c9a-8d3e-1a2b3c4d5e72",
      "status": "paid",
      "type": "pix",
      "amount": 1200
    }
  }
}

Exemplo de webhook de assinatura

{
  "api_version": "v2",
  "id": "120ebf7cc24835b5ea33ee617bf70cb91c3a4dcd7413afcb05f61c60d1c9de3d",
  "event": "subscription",
  "url": "https://shop.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"
    }
  }
}

Assinaturas com Pix Automático usam o mesmo envelope. As cobranças delas chegam só como eventos de assinatura, sem evento transaction.*, e o primeiro evento depende de haver período de teste. Veja a sequência do Pix Automático em Webhooks de assinatura.

Verificando a assinatura HMAC

Quando um webhook tem Token de Segurança, verifique estes headers antes de confiar no corpo:

Header	Valor
`X-Pagou-Timestamp`	Tempo Unix em segundos, como string
`X-Pagou-Signature`	`sha256=` seguido do digest HMAC-SHA256 em hexadecimal

A chave do HMAC é o Token de Segurança. A mensagem é o timestamp, um . e o corpo HTTP exato:

{X-Pagou-Timestamp}.{rawBody}

rawBody é o corpo HTTP exato que você recebeu. Um webhook sem Token de Segurança vai sem assinatura. Postbacks de notify_url vão sem assinatura. Defina o Token de Segurança no painel em Configurações → Integrações ao criar ou editar o webhook. O campo diz “Gerado automaticamente se vazio.” Deixe em branco para gerar automaticamente. Reconciliar o recurso com GET continua recomendado. Uma verificação executável está no exemplo de webhooks em TypeScript.

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

Exemplos executáveis

Veja código pronto e testável para este fluxo em Exemplos de Webhooks — executável em sete linguagens no sandbox.

​Comparação de envelopes

​Exemplo de webhook de pagamento

​Exemplo de webhook de transferência

​Exemplo de webhook de assinatura

​Verificando a assinatura HMAC

​Resposta de ACK

​Erro comum de ingestão

​Guia de mapeamento

​Leia a seguir

​Exemplos executáveis