Webhooks are the primary mechanism the Pix Indirect Plugin (BTG) uses to notify you about Pix-related events in real time. Instead of relying on synchronous responses, you receive asynchronous, event-driven callbacks whenever relevant changes occur in Pix operations — such as transfers, refunds, key claims, or MED-related events. This model ensures:

Near real-time updates
Decoupled integrations
Reliable reconciliation and operational traceability

Webhooks described on this page currently apply to the Indirect Pix model via BTG.Direct Pix webhooks may differ depending on the connectivity model and are documented separately.

Prerequisites

Before configuring webhooks, ensure you have:

The Pix Indirect Plugin configured and running (see Indirect Pix via BTG)
An HTTPS endpoint ready to receive webhook requests
Basic understanding of Pix event lifecycle and transaction flows

Why webhooks matter in Pix

Pix is an asynchronous, multi-party system. Even when an API request succeeds, the final state of a transaction is only confirmed later, after settlement and counterparty acknowledgment. Webhooks allow your system to:

Track authoritative transaction status
React to refunds, reversals, and MED events
Maintain ledger and operational consistency
Reduce polling and operational overhead

Event types

You receive events grouped by flow and entity, aligned with BACEN (Banco Central do Brasil) domains.

Flow	Entity	Description
DICT	CLAIM	Pix key portability and ownership claim events
DICT	INFRACTION_REPORT	MED (Mecanismo Especial de Devolução) infraction reports and dispute lifecycle
DICT	REFUND	MED refund request events
TRANSFER	CASHIN	Incoming Pix payment status updates
TRANSFER	CASHOUT	Outgoing Pix payment status updates
REFUND	CASHIN	Incoming Pix refund status updates
REFUND	CASHOUT	Outgoing Pix refund status updates

Each event reflects a state transition in the Pix ecosystem and should be treated as the source of truth.

DICT (Diretório de Identificadores de Contas Transacionais) is the BACEN directory that manages Pix keys and related operations like claims, infractions, and refunds.

Webhook configuration

You enable webhooks by configuring destination URLs and selecting which event types your system should receive.

Environment variables

You can configure webhook endpoints at entity, flow, or global level.

Flow	Entity	Entity URL	Module URL
DICT	CLAIM	`WEBHOOK_DICT_CLAIM_URL`	`WEBHOOK_DICT_URL`
DICT	INFRACTION_REPORT	`WEBHOOK_DICT_INFRACTION_REPORT_URL`	`WEBHOOK_DICT_URL`
DICT	REFUND	`WEBHOOK_DICT_REFUND_URL`	`WEBHOOK_DICT_URL`
TRANSFER	CASHIN	`WEBHOOK_TRANSFER_CASHIN_URL`	`WEBHOOK_TRANSFER_URL`
TRANSFER	CASHOUT	`WEBHOOK_TRANSFER_CASHOUT_URL`	`WEBHOOK_TRANSFER_URL`
REFUND	CASHIN	`WEBHOOK_REFUND_CASHIN_URL`	`WEBHOOK_REFUND_URL`
REFUND	CASHOUT	`WEBHOOK_REFUND_CASHOUT_URL`	`WEBHOOK_REFUND_URL`

URL resolution priority

When multiple URLs are configured, the system resolves them in the following order:

Entity-level URL Example: WEBHOOK_DICT_CLAIM_URL
Flow-level URL Example: WEBHOOK_DICT_URL
Default URL WEBHOOK_DEFAULT_URL

This gives you fine-grained routing control without duplicating infrastructure.

Request format

Headers

Every webhook request includes standardized headers for traceability and security.

Header	Description
`Content-Type`	`application/json`
`X-Request-ID`	Unique request identifier
`X-Entity-Type`	Event entity (e.g. `INFRACTION_REPORT`)
`X-Flow-Type`	Source domain (e.g. `DICT`)
`Idempotency-Key`	Unique event identifier for deduplication

Body structure

{
  "entityType": "INFRACTION_REPORT",
  "flowType": "DICT",
  "payload": {
    ...
  }
}

Field	Description
`entityType`	Event entity
`flowType`	Pix domain
`payload`	Event-specific data

The payload schema varies per event type but always represents a state change.

Responses and retry behavior

Expected response

Your endpoint must return an HTTP 2xx status to confirm successful delivery.

Response	Result
2xx	Delivered successfully
Non-2xx	Retried automatically

Retry strategy

Failed deliveries are retried automatically using exponential backoff:

Attempt	Delay
1	1 second
2	2 seconds
3	4 seconds

Defaults

Max retries: 3
Timeout per request: 30 seconds

After all retries fail, the event is moved to a failure queue for operational follow-up.

Custom retry settings

Retries and timeouts can be customized per event:

WEBHOOK_DICT_INFRACTION_REPORT_MAX_RETRIES=5
WEBHOOK_DICT_INFRACTION_REPORT_REQUEST_TIMEOUT=60s

Circuit breaker protection

To prevent cascading failures, webhook delivery is protected by a circuit breaker. When the Pix Plugin detects repeated delivery failures (typically consecutive 5xx responses or timeouts), it temporarily pauses webhook calls to the affected endpoint. After a configurable cooldown period, the system performs controlled retry attempts to check if the endpoint has recovered. Once successful responses are detected, normal delivery is automatically resumed. This mechanism ensures:

Protection against overloaded or unstable endpoints
Graceful recovery without manual intervention
Higher overall system stability in production environments

Circuit breaker behavior works alongside retries and exponential backoff, adding an extra safety layer for webhook delivery.

Best practices

Practice	Why it matters
Ignore unknown fields	Remain forward-compatible as new fields are added
Idempotent processing	Use `Idempotency-Key` to avoid processing duplicates
Fast acknowledgment	Return `202 Accepted` and process asynchronously
Async processing	Avoid blocking the webhook thread
Handle compression	Payloads >1KB are gzip-compressed. Check the `Content-Encoding` header and decompress accordingly

Event examples

Below are representative examples of webhook payloads you receive from the Pix Indirect Plugin.

DICT claim

Ownership or portability lifecycle events. Use these to track Pix key disputes across institutions.

{
  "entityType": "CLAIM",
  "flowType": "DICT",
  "payload": {
    "id": "claim-7f8a9b2c-1234-5678-abcd-ef0123456789",
    "key": "+5511999998888",
    "keyType": "PHONE",
    "claimType": "PORTABILITY",
    "claimer": {
      "ispb": "12345678",
      "name": "Banco Exemplo S.A."
    },
    "donor": {
      "ispb": "87654321",
      "name": "Outra Instituição S.A."
    },
    "status": "CONFIRMED",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T14:45:00Z"
  }
}

DICT infraction report (MED)

Dispute and fraud signaling events aligned with BACEN MED rules.

{
  "entityType": "INFRACTION_REPORT",
  "flowType": "DICT",
  "payload": {
    "id": "infraction-3e4f5a6b-7890-1234-cdef-567890abcdef",
    "endToEndId": "E12345678202401151030abcdefghij12",
    "infractionType": "FRAUD",
    "reportedBy": {
      "ispb": "12345678",
      "name": "Banco Exemplo S.A."
    },
    "reportedAgainst": {
      "ispb": "87654321",
      "name": "Outra Instituição S.A."
    },
    "status": "OPEN",
    "analysisResult": null,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

DICT refund (MED)

Refund requests and decisions related to MED cases.

{
  "entityType": "REFUND",
  "flowType": "DICT",
  "payload": {
    "id": "refund-9a8b7c6d-5432-1098-fedc-ba0987654321",
    "endToEndId": "E12345678202401151030abcdefghij12",
    "infractionId": "infraction-3e4f5a6b-7890-1234-cdef-567890abcdef",
    "refundAmount": 150.00,
    "refundReason": "FRAUD",
    "status": "REQUESTED",
    "requestedBy": {
      "ispb": "12345678",
      "name": "Banco Exemplo S.A."
    },
    "createdAt": "2024-01-16T09:00:00Z",
    "updatedAt": "2024-01-16T09:00:00Z"
  }
}

Transfer cash-in and cash-out

Incoming and outgoing Pix transfer events. Cash-in (incoming transfer):

{
  "entityType": "CASHIN",
  "flowType": "TRANSFER",
  "payload": {
    "id": "transfer-1a2b3c4d-5678-90ab-cdef-1234567890ab",
    "endToEndId": "E12345678202401151030abcdefghij12",
    "amount": 250.00,
    "payer": {
      "ispb": "87654321",
      "name": "João Silva",
      "cpfCnpj": "12345678901"
    },
    "payee": {
      "ispb": "12345678",
      "name": "Maria Santos",
      "cpfCnpj": "98765432100",
      "accountNumber": "12345-6"
    },
    "status": "SETTLED",
    "createdAt": "2024-01-15T10:30:00Z",
    "settledAt": "2024-01-15T10:30:05Z"
  }
}

Cash-out (outgoing transfer):

{
  "entityType": "CASHOUT",
  "flowType": "TRANSFER",
  "payload": {
    "id": "transfer-2b3c4d5e-6789-01bc-def0-2345678901bc",
    "endToEndId": "E87654321202401151045zyxwvutsrqp98",
    "amount": 500.00,
    "payer": {
      "ispb": "12345678",
      "name": "Maria Santos",
      "cpfCnpj": "98765432100",
      "accountNumber": "12345-6"
    },
    "payee": {
      "ispb": "87654321",
      "name": "Empresa ABC Ltda",
      "cpfCnpj": "12345678000199"
    },
    "status": "SETTLED",
    "createdAt": "2024-01-15T10:45:00Z",
    "settledAt": "2024-01-15T10:45:03Z"
  }
}

Refund cash-in and cash-out

Refund settlement events for Pix transactions. Refund cash-in (receiving a refund):

{
  "entityType": "CASHIN",
  "flowType": "REFUND",
  "payload": {
    "id": "refund-4d5e6f7g-8901-23cd-ef01-4567890123cd",
    "originalEndToEndId": "E87654321202401151045zyxwvutsrqp98",
    "refundEndToEndId": "D12345678202401161000refund123456",
    "amount": 500.00,
    "reason": "CUSTOMER_REQUEST",
    "status": "SETTLED",
    "createdAt": "2024-01-16T10:00:00Z",
    "settledAt": "2024-01-16T10:00:02Z"
  }
}

Refund cash-out (sending a refund):

{
  "entityType": "CASHOUT",
  "flowType": "REFUND",
  "payload": {
    "id": "refund-5e6f7g8h-9012-34de-f012-5678901234de",
    "originalEndToEndId": "E12345678202401151030abcdefghij12",
    "refundEndToEndId": "D87654321202401161015refund789012",
    "amount": 250.00,
    "reason": "OPERATIONAL_FLAW",
    "status": "SETTLED",
    "createdAt": "2024-01-16T10:15:00Z",
    "settledAt": "2024-01-16T10:15:04Z"
  }
}

Key takeaway

Webhooks are not optional in Pix Indirect operations. They are the authoritative channel for transaction state, refunds, and dispute handling. A correct webhook implementation ensures:

Accurate reconciliation
Regulatory compliance
Operational resilience
Predictable customer experience

For production environments, always design webhook consumers as idempotent, asynchronous, and observable systems.

Next steps

Now that you understand how webhooks work in Indirect Pix, explore these related topics:

Indirect Pix via BTG - Initial setup and configuration
Pix main domains: transfers - Deep dive into transfer operations
Pix main domains: DICT - Understanding DICT operations and key management
Pix main domains: MED - MED dispute and refund handling

Introduction

CRM

Fees Engine

Pix

Indirect Pix

Direct Pix

Webhooks

Prerequisites

Why webhooks matter in Pix

Event types

Webhook configuration

Environment variables

URL resolution priority

Request format

Headers

Body structure

Responses and retry behavior

Expected response

Retry strategy

Custom retry settings

Circuit breaker protection

Best practices

Event examples

DICT claim

DICT infraction report (MED)

DICT refund (MED)

Transfer cash-in and cash-out

Refund cash-in and cash-out

Key takeaway

Next steps

Introduction

CRM

Fees Engine

Pix

Indirect Pix

Direct Pix

​Prerequisites

​Why webhooks matter in Pix

​Event types

​Webhook configuration

​Environment variables

​URL resolution priority

​Request format

​Headers

​Body structure

​Responses and retry behavior

​Expected response

​Retry strategy

​Custom retry settings

​Circuit breaker protection

​Best practices

​Event examples

​DICT claim

​DICT infraction report (MED)

​DICT refund (MED)

​Transfer cash-in and cash-out

​Refund cash-in and cash-out

​Key takeaway

​Next steps

Prerequisites

Why webhooks matter in Pix

Event types

Webhook configuration

Environment variables

URL resolution priority

Request format

Headers

Body structure

Responses and retry behavior

Expected response

Retry strategy

Custom retry settings

Circuit breaker protection

Best practices

Event examples

DICT claim

DICT infraction report (MED)

DICT refund (MED)

Transfer cash-in and cash-out

Refund cash-in and cash-out

Key takeaway

Next steps