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

​
When to use webhooks

  • Payment state changes for Pix and card flows
  • 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

{
  "external_ref": "order_1001",
  "amount": 1500,
  "currency": "BRL",
  "method": "pix",
  "notify_url": "https://merchant.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

{
  "received": true
}

​
Common ingestion error

Status 400 
{
  "error": "missing_event_id"
}
Fix: validate the top-level webhook id before enqueueing work. Deduplicate by that ID, then process asynchronously.
  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