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

# Webhook Fundamentals

> Use webhooks as the primary source of truth for asynchronous payment, subscription, and payout updates, with polling only as a fallback.

Use webhooks to drive payment, subscription, and payout state. Use polling only for debugging, recovery, or reconciliation.

## When to use webhooks

* Payment state changes for Pix, voucher, and card flows
* Subscription renewals, failures, updates, and cancellation
* Pix Out transfer progression and settlement
* Fast order and payout updates without frontend polling

## Delivery patterns

### Central subscriptions

Use one stable endpoint when you want a shared ingestion pipeline for all recurring events.

### Per-request callbacks

Set `notify_url` on a specific transaction or transfer when only one workflow should receive that callback.

## Example request with `notify_url`

```json theme={null}
{
  "external_ref": "order_1001",
  "amount": 1500,
  "currency": "BRL",
  "method": "pix",
  "notify_url": "https://shop.example/webhooks/pagou",
  "buyer": {
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "document": {
      "type": "CPF",
      "number": "12345678901"
    }
  },
  "products": [
    {
      "name": "Starter order",
      "price": 1500,
      "quantity": 1
    }
  ]
}
```

## Minimal ACK response

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

## Common ingestion error

Status `400`

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

Fix: validate the top-level webhook `id` before enqueueing work. Deduplicate by that ID, then process asynchronously.

## Recommended ingestion flow

1. Accept the HTTPS `POST`.
2. Validate the top-level event ID.
3. Return `200 OK` quickly.
4. Persist or enqueue the payload.
5. Reconcile with `GET` if your worker crashes or a downstream side effect is uncertain.

## Next steps

* [Webhooks Overview](/webhooks/overview)
* [Payment Events](/webhooks/payment-events)
* [Subscription Webhooks](/subscriptions/webhooks)
* [Transfer Events](/webhooks/transfer-events)