> ## 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.

# Webhooks Overview

> Build one resilient webhook ingestion path for payment, subscription, and payout events.

Pagou currently exposes three public webhook families. Payment and subscription webhooks use an `event` envelope. Transfer webhooks use a payout `type` envelope.

## Envelope comparison

| Domain        | Top-level event field   | Resource field | Concrete event name |
| ------------- | ----------------------- | -------------- | ------------------- |
| Payments      | `event: "transaction"`  | `data`         | `data.event_type`   |
| Subscriptions | `event: "subscription"` | `data`         | `data.event_type`   |
| Transfers     | `type`                  | `data.object`  | top-level `type`    |

## Payment webhook example

```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` echoes the custom `informations` you sent when creating the transaction via the API; it is present only when you sent custom entries. See [Payment Events](/webhooks/payment-events).

## Transfer webhook example

```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
    }
  }
}
```

## Subscription webhook example

```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"
    }
  }
}
```

## ACK response

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

## Common ingestion error

```json theme={null}
{
  "error": "missing_event_id"
}
```

Fix: require the top-level `id`, deduplicate by that value, return `200 OK` quickly, and process asynchronously.

## Mapping guidance

* Drive business state from resource status, not from a frontend guess.
* Route subscription lifecycle changes from `data.event_type`.
* Map transfer event `payout.transferred` to settled resource status `paid`.
* Reconcile if your worker crashes after acknowledgement.

## Read next

* [Payment Events](/webhooks/payment-events)
* [Subscription Webhooks](/subscriptions/webhooks)
* [Transfer Events](/webhooks/transfer-events)
* [Retries and Reconciliation](/webhooks/retries-and-reconciliation)

## Runnable examples

See working, testable code for this flow in the [Webhooks examples](/examples/webhooks) — runnable in seven languages against the sandbox.