Webhooks Overview - Pagou Developer Docs

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

{
  "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" }
    ],
    "customer": {
      "name": "Ana Souza",
      "email": "ana@example.com",
      "phone": "+5511999998888"
    },
    "products": [
      {
        "id": "018f1f2e-7b42-7c9a-8d3e-9f0a1b2c3d4e",
        "title": "Curso completo",
        "unit_price": 1500,
        "quantity": 1,
        "tangible": false,
        "kind": "product"
      }
    ],
    "attribution": {
      "utm_source": "instagram",
      "utm_medium": "cpc",
      "utm_campaign": "black-friday",
      "utm_content": null,
      "utm_term": null,
      "fbc": null,
      "fbp": null,
      "gclid": null,
      "ttclid": null,
      "src": null,
      "sck": null,
      "checkout_url": "https://pay.example/checkout/abc",
      "checkout_url_declared": null,
      "referrer_url": "https://instagram.com/"
    }
  }
}

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. Transaction events also carry data.customer (buyer name, email and phone — never the document), data.products (purchased line items, same shape as the transaction detail endpoint) and data.attribution (campaign UTMs, ad click IDs, affiliate src/sck, the checkout URL we derive and the one someone declared, plus the referrer). All are optional: customer and attribution can be null, products can be empty, and attribution is always null for API-created transactions. See Payment Events.

Transfer webhook example

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

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

Pix Automático subscriptions use the same envelope. Their charges arrive only as subscription events, with no transaction.* event, and the first event depends on whether the subscription has a trial. See the Pix Automático sequence in Subscription Webhooks.

Verifying signatures

When a webhook has a Security Token, verify these headers before you trust the body:

Header	Value
`X-Pagou-Timestamp`	Unix time in seconds, as a string
`X-Pagou-Signature`	`sha256=` followed by the HMAC-SHA256 hex digest

The HMAC key is the Security Token. The message is the timestamp, a ., and the exact HTTP body:

{X-Pagou-Timestamp}.{rawBody}

rawBody is the exact HTTP body you received. A webhook with no Security Token is unsigned. notify_url postbacks are unsigned. Set the Security Token in the dashboard under Settings → Integrations when you create or edit the webhook. The field reads “Generated automatically if empty.” Leave it blank to generate one automatically. Reconciling the resource with GET remains recommended. A runnable check is in the TypeScript webhooks example.

ACK response

{
  "received": true
}

Common ingestion error

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

Runnable examples

See working, testable code for this flow in the Webhooks examples — runnable in seven languages against the sandbox.

​Envelope comparison

​Payment webhook example

​Transfer webhook example

​Subscription webhook example

​Verifying signatures

​ACK response

​Common ingestion error

​Mapping guidance

​Read next

​Runnable examples