> ## Documentation Index
> Fetch the complete documentation index at: https://developer.pagou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Visão geral de webhooks

> Monte um pipeline resiliente para receber eventos de pagamento, assinatura e payout.

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

```json theme={null}
{
  "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" }
    ]
  }
}
```

`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](/webhooks/payment-events).

## Exemplo de webhook de transferência

```json theme={null}
{
  "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

```json theme={null}
{
  "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"
    }
  }
}
```

## Resposta de ACK

```json theme={null}
{
  "received": true
}
```

## Erro comum de ingestão

```json theme={null}
{
  "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

* [Eventos de pagamento](/pt/webhooks/payment-events)
* [Webhooks de assinatura](/pt/subscriptions/webhooks)
* [Eventos de transferência](/pt/webhooks/transfer-events)
* [Retentativas e reconciliação](/pt/webhooks/retries-and-reconciliation)

## Exemplos executáveis

Veja código pronto e testável para este fluxo em [Exemplos de Webhooks](/pt/examples/webhooks) — executável em sete linguagens no sandbox.