Webhook Fundamentals

​

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

​

Per-request callbacks

​

Example request with notify_url

{
  "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

{
  "received": true
}

​

Common ingestion error

{
  "error": "missing_event_id"
}

​

Signatures

​

Recommended ingestion flow

1. Accept the HTTPS POST.
2. When the webhook has a Security Token, verify the signature. See Verifying signatures.
3. Validate the top-level event ID.
4. Return 200 OK quickly.
5. Persist or enqueue the payload.
6. Reconcile with GET if your worker crashes or a downstream side effect is uncertain.

​

Next steps

• Verifying signatures
• Webhooks Overview
• Payment Events
• Subscription Webhooks
• Transfer Events