Webhooks are the primary mechanism the Pix Indirect Plugin (BTG) uses to notify you about Pix-related events in real time. You do not rely on synchronous responses. Instead, you receive asynchronous, event-driven callbacks when relevant changes occur in Pix operations — transfers, refunds, key claims, or MED events. This model gives you:

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

These webhooks apply only to the Indirect Pix model via BTG.Direct Pix webhooks can differ by connectivity model. A separate page documents them.

Prerequisites

Before you configure webhooks, make sure you have:

The Pix Indirect Plugin configured and running (see How indirect participation works)
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. An API request can succeed before the transaction reaches its final state. The system confirms that state 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
DICT	FUNDS_RECOVERY	MED 2.0 Funds Recovery entity status changes (DB-backed)
DICT	FUNDS_RECOVERY_EVENT	MED 2.0 Funds Recovery lifecycle events (pass-through)
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. Treat each event as the source of truth.

The two MED 2.0 entities behave differently. The plugin emits FUNDS_RECOVERY after it updates its local record. FUNDS_RECOVERY_EVENT is a pass-through of BTG lifecycle events with no database update. See MED 2.0 — Funds Recovery for the full flow.

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

To enable webhooks, configure the destination URLs and select which event types your system receives.

Environment variables

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

Flow	Entity	Entity-level URL variable
DICT	CLAIM	`WEBHOOK_DICT_CLAIM_URL`
DICT	INFRACTION_REPORT	`WEBHOOK_DICT_INFRACTION_REPORT_URL`
DICT	REFUND	`WEBHOOK_DICT_REFUND_URL`
TRANSFER	CASHIN	`WEBHOOK_TRANSFER_CASHIN_URL`
TRANSFER	CASHOUT	`WEBHOOK_TRANSFER_CASHOUT_URL`
REFUND	CASHIN	`WEBHOOK_REFUND_CASHIN_URL`
REFUND	CASHOUT	`WEBHOOK_REFUND_CASHOUT_URL`

Each flow also has a flow-level URL for all its entities. The plugin uses it when no entity-level URL exists: WEBHOOK_DICT_URL, WEBHOOK_TRANSFER_URL, and WEBHOOK_REFUND_URL.

URL resolution priority

When you configure multiple URLs, the plugin resolves them in this 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 and no duplicate 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

The plugin retries failed deliveries automatically with 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 plugin moves the event to a dead-letter queue for operational follow-up.

Custom retry settings

You can customize retries and timeouts per event:

WEBHOOK_DICT_INFRACTION_REPORT_MAX_RETRIES=5
WEBHOOK_DICT_INFRACTION_REPORT_REQUEST_TIMEOUT=60s

Circuit breaker protection

A circuit breaker protects webhook delivery and prevents cascading failures. 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. When the endpoint returns successful responses, the plugin resumes normal delivery automatically. This mechanism gives you:

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

The circuit breaker works alongside retries and exponential backoff. It adds an extra safety layer for webhook delivery.

Transport errors and orphan events

When the plugin receives a refund webhook, it looks up the original transfer along the cash-in → cash-out chain. If no local source matches, the plugin persists the refund as an orphan record for BACEN auditability. It does not drop the refund, so the record stays visible for reconciliation and follow-up. If a source lookup fails at the transport layer, the plugin skips that source and continues. When no source resolves — from a clean miss or a swallowed transport error — the plugin records the refund as an orphan. The plugin aborts only when the transfer-lookup bridge is not configured. originalEndToEndId is the canonical key for all refund lookups. The plugin resolves refunds from both the cash-in → refund and cash-out → refund directions with this field. Always key refunds by originalEndToEndId (the original transfer’s end-to-end ID), not by a single direction-specific lookup path.

Internal transaction reports (intra-PSP)

The plugin settles intra-PSP (P2P) transfers internally. They never reach BTG for settlement, but the plugin still reports them to BACEN through the TRCK002 abstraction. BTG confirms report status through a CAMT025 webhook that carries the entity PixInternalTransactionsReport.

Field	Description
`pactualId`	BTG-assigned report identifier
`clientRequestId`	Your idempotency key, sent during report submission
`entity`	Always `PixInternalTransactionsReport`
`status`	`PROCESSING`, `CONFIRMED`, or `ERROR`
`errorCode` / `errorDescription`	Populated when `status = ERROR`

The plugin updates the report status when the CAMT025 report webhook confirms or fails. The outbound webhooks fire earlier, when the intra-PSP transfer settles: cashin.completed for the cash-in leg and cashout.completed or cashout.failed for the cash-out leg. For the full internal flow, see Intra-PSP transfers.

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. Expand each entry to view its payload.

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

DICT funds recovery (MED 2.0)

Funds Recovery entity status changes. The plugin updates its local record before forwarding the full entity.

{
  "entityType": "FUNDS_RECOVERY",
  "flowType": "DICT",
  "payload": {
    "id": "91d65e98-97c0-4b0f-b577-73625da1f9fc",
    "externalId": "ca1b9c01-ff9e-4a58-90ab-d31512e15ce0",
    "accountId": "01989f9e-6508-79f8-9540-835be49fbd0d",
    "status": "CREATED",
    "rootTransactionId": "E9999901012341234123412345678900",
    "situationType": "SCAM",
    "reporterParticipant": "99999010",
    "contactInformation": {},
    "reportDetails": "Details to help receiving participants",
    "createdAt": "2020-01-17T10:00:00.000Z",
    "updatedAt": "2020-01-17T10:00:00.000Z"
  }
}

Lifecycle events arrive as entityType: FUNDS_RECOVERY_EVENT (pass-through, no DB update), with event values such as FUNDS_RECOVERY_ANALYSED and FUNDS_RECOVERY_COMPLETED.

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 gives you:

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:

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
MED 2.0 — Funds Recovery - Cross-account fraud recovery and its webhooks
Intra-PSP transfers - Internal P2P settlement and TRCK002 reporting
API reference — Full API documentation for DICT, Claims, Transactions, QR Codes, and MED operations

Overview

Lerian SPI — native messaging

JD — interface (direct Pix)

BTG — interface (indirect 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

Transport errors and orphan events

Internal transaction reports (intra-PSP)

Best practices

Event examples

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

​Transport errors and orphan events

​Internal transaction reports (intra-PSP)

​Best practices

​Event examples

​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

Transport errors and orphan events

Internal transaction reports (intra-PSP)

Best practices

Event examples

Key takeaway

Next steps