Webhooks - PIX-OUT

🔄 Webhooks de Saque (Withdrawal / PIX-OUT)

Receba atualizações em tempo real sobre o status dos saques por meio de notificações de webhook.

🧭 Visão Geral

Os webhooks permitem que sua aplicação receba notificações automáticas sempre que o status de um saque for atualizado em nosso sistema.
Em vez de consultar constantemente a API em busca de atualizações, os webhooks enviam os dados do saque diretamente para sua aplicação assim que o evento acontece.

🚀 Configurando Webhooks

Existem duas formas de receber notificações sobre saques:

Opção 1: Postback por Saque (via API)

Informe o campo postback_url na requisição de Criação de Saque (Payout Request). O webhook será enviado exclusivamente para aquele saque específico.

O payload é enviado como JSON direto (sem envelope).

Ideal para integrações onde cada saque tem uma URL de callback diferente.

Opção 2: Webhook Global (via Painel)

Configure um webhook pelo painel de Integrações na plataforma, selecionando um dos tipos de evento disponíveis.

O payload do postback é enviado dentro de um envelope estruturado com event, timestamp e data.

Inclui o header X-Webhook-Signature com assinatura HMAC-SHA256 para validação.

Ideal para receber todos os eventos de saque em um único endpoint.

As duas opções podem ser usadas simultaneamente — o mesmo saque pode disparar tanto o postback individual quanto o webhook global.

📡 Tipos de Evento (Webhook Global)

Ao configurar um webhook via painel, selecione o tipo de evento desejado:

Tipo de Evento	Descrição
`withdrawal.*`	Todos os eventos de saque (pending, processing, completed, failed, cancelled).
`withdrawal.pending`	O saque foi criado e está aguardando processamento.
`withdrawal.processing`	O saque está sendo processado pela instituição financeira.
`withdrawal.completed`	O saque foi concluído com sucesso.
`withdrawal.failed`	O saque falhou.
`withdrawal.cancelled`	O saque foi cancelado.

📦 Exemplos de Payload

Quando o status de um saque é alterado, nosso sistema envia uma requisição POST para a URL configurada.

O conteúdo do payload varia conforme a opção de configuração e o status do saque.

⏳ Saque Pendente

Postback (via API):

{
  "id": 5722,
  "status": "pending",
  "amount": 500,
  "type": "withdrawal",
  "external_id": "MEU-ID-EXTERNO-PAYOUT-789",
  "end_to_end_id": null,
  "rejection_reason": null,
  "created_at": "2025-11-10T23:38:00-03:00",
  "payer": null,
  "payee": null
}

Webhook Global (via Painel):

{
  "event": "withdrawal.pending",
  "timestamp": "2025-11-10T23:38:00Z",
  "data": {
    "id": 5722,
    "status": "pending",
    "amount": 500,
    "type": "withdrawal",
    "external_id": "MEU-ID-EXTERNO-PAYOUT-789",
    "end_to_end_id": null,
    "rejection_reason": null,
    "created_at": "2025-11-10T23:38:00-03:00",
    "payer": null,
    "payee": null
  }
}

⏳ Saque em Processamento

Postback (via API):

{
  "id": 5722,
  "status": "processing",
  "amount": 500,
  "type": "withdrawal",
  "external_id": "MEU-ID-EXTERNO-PAYOUT-789",
  "end_to_end_id": null,
  "created_at": "2025-11-10T23:38:00-03:00",
  "rejection_reason": null,
  "payer": null,
  "payee": null
}

Webhook Global (via Painel):

{
  "event": "withdrawal.processing",
  "timestamp": "2025-11-10T23:38:05Z",
  "data": {
    "id": 5722,
    "status": "processing",
    "amount": 500,
    "type": "withdrawal",
    "external_id": "MEU-ID-EXTERNO-PAYOUT-789",
    "end_to_end_id": null,
    "created_at": "2025-11-10T23:38:00-03:00",
    "rejection_reason": null,
    "payer": null,
    "payee": null
  }
}

⏳ Saque em Processamento (com dados do pagador)

O evento de processamento pode já incluir os dados do pagador:

Postback (via API):

{
  "id": 8327,
  "status": "processing",
  "amount": 500,
  "type": "withdrawal",
  "external_id": "8327_394453",
  "end_to_end_id": null,
  "created_at": "2025-11-14T17:24:24-03:00",
  "rejection_reason": null,
  "payer": {
    "bank": {
      "account": "12345678",
      "agency": "1234",
      "digit": "9",
      "name": "Banco do Brasil",
      "type": "Conta Corrente"
    },
    "document": "12.345.678/0001-95",
    "name": "Empresa do Henrique"
  },
  "payee": null
}

Webhook Global (via Painel):

{
  "event": "withdrawal.processing",
  "timestamp": "2025-11-14T17:24:30Z",
  "data": {
    "id": 8327,
    "status": "processing",
    "amount": 500,
    "type": "withdrawal",
    "external_id": "8327_394453",
    "end_to_end_id": null,
    "created_at": "2025-11-14T17:24:24-03:00",
    "rejection_reason": null,
    "payer": {
      "bank": {
        "account": "12345678",
        "agency": "1234",
        "digit": "9",
        "name": "Banco do Brasil",
        "type": "Conta Corrente"
      },
      "document": "12.345.678/0001-95",
      "name": "Empresa do Henrique"
    },
    "payee": null
  }
}

⏳ Saque em Processamento (com dados completos)

Postback (via API):

{
  "id": 5723,
  "status": "processing",
  "amount": 500,
  "type": "withdrawal",
  "external_id": "MEU-ID-EXTERNO-PAYOUT-789",
  "end_to_end_id": "E071368472025110714410CSR1MUA0ZT",
  "created_at": "2025-11-10T23:38:00-03:00",
  "rejection_reason": null,
  "payer": {
    "bank": {
      "account": "12345678",
      "agency": "1234",
      "digit": "9",
      "name": "Banco do Brasil",
      "type": "Conta Corrente"
    },
    "document": "12.345.678/0001-95",
    "name": "Empresa do Henrique"
  },
  "payee": {
    "bank_code": "10573521",
    "document": ".434.275-*",
    "name": "Pedro de Alcântara Francisco Antônio"
  }
}

Webhook Global (via Painel):

{
  "event": "withdrawal.processing",
  "timestamp": "2025-11-10T23:38:10Z",
  "data": {
    "id": 5723,
    "status": "processing",
    "amount": 500,
    "type": "withdrawal",
    "external_id": "MEU-ID-EXTERNO-PAYOUT-789",
    "end_to_end_id": "E071368472025110714410CSR1MUA0ZT",
    "created_at": "2025-11-10T23:38:00-03:00",
    "rejection_reason": null,
    "payer": {
      "bank": {
        "account": "12345678",
        "agency": "1234",
        "digit": "9",
        "name": "Banco do Brasil",
        "type": "Conta Corrente"
      },
      "document": "12.345.678/0001-95",
      "name": "Empresa do Henrique"
    },
    "payee": {
      "bank_code": "10573521",
      "document": ".434.275-*",
      "name": "Pedro de Alcântara Francisco Antônio"
    }
  }
}

✅ Saque Concluído com Sucesso

Postback (via API):

{
  "id": 5723,
  "status": "completed",
  "amount": 500,
  "type": "withdrawal",
  "external_id": "MEU-ID-EXTERNO-PAYOUT-789",
  "end_to_end_id": "E071368472025110714410CSR1MUA0ZT",
  "created_at": "2025-11-10T23:38:00-03:00",
  "rejection_reason": null,
  "payer": {
    "bank": {
      "account": "12345678",
      "agency": "1234",
      "digit": "9",
      "name": "Banco do Brasil",
      "type": "Conta Corrente"
    },
    "document": "12.345.678/0001-95",
    "name": "Empresa do Henrique"
  },
  "payee": {
    "bank_code": "10573521",
    "document": ".434.275-*",
    "name": "Pedro de Alcântara Francisco Antônio"
  }
}

Webhook Global (via Painel):

{
  "event": "withdrawal.completed",
  "timestamp": "2025-11-10T23:40:00Z",
  "data": {
    "id": 5723,
    "status": "completed",
    "amount": 500,
    "type": "withdrawal",
    "external_id": "MEU-ID-EXTERNO-PAYOUT-789",
    "end_to_end_id": "E071368472025110714410CSR1MUA0ZT",
    "created_at": "2025-11-10T23:38:00-03:00",
    "rejection_reason": null,
    "payer": {
      "bank": {
        "account": "12345678",
        "agency": "1234",
        "digit": "9",
        "name": "Banco do Brasil",
        "type": "Conta Corrente"
      },
      "document": "12.345.678/0001-95",
      "name": "Empresa do Henrique"
    },
    "payee": {
      "bank_code": "10573521",
      "document": ".434.275-*",
      "name": "Pedro de Alcântara Francisco Antônio"
    }
  }
}

❌ Saque Rejeitado

Postback (via API):

{
  "id": 8179,
  "status": "rejected",
  "amount": 500,
  "type": "withdrawal",
  "external_id": "MEU-ID-EXTERNO-PAYOUT-789",
  "end_to_end_id": null,
  "created_at": "2025-11-10T23:38:00-03:00",
  "rejection_reason": "Motivo da Rejeição",
  "payer": {
    "bank": {
      "account": "12345678",
      "agency": "1234",
      "digit": "9",
      "name": "Banco do Brasil",
      "type": "Conta Corrente"
    },
    "document": "12.345.678/0001-95",
    "name": "Empresa do Henrique"
  },
  "payee": null
}

Webhook Global (via Painel):

{
  "event": "withdrawal.failed",
  "timestamp": "2025-11-10T23:40:00Z",
  "data": {
    "id": 8179,
    "status": "rejected",
    "amount": 500,
    "type": "withdrawal",
    "external_id": "MEU-ID-EXTERNO-PAYOUT-789",
    "end_to_end_id": null,
    "created_at": "2025-11-10T23:38:00-03:00",
    "rejection_reason": "Motivo da Rejeição",
    "payer": {
      "bank": {
        "account": "12345678",
        "agency": "1234",
        "digit": "9",
        "name": "Banco do Brasil",
        "type": "Conta Corrente"
      },
      "document": "12.345.678/0001-95",
      "name": "Empresa do Henrique"
    },
    "payee": null
  }
}

❌ Saque Falhou

Postback (via API):

{
  "id": 8179,
  "status": "failed",
  "amount": 500,
  "type": "withdrawal",
  "external_id": "MEU-ID-EXTERNO-PAYOUT-789",
  "end_to_end_id": null,
  "created_at": "2025-11-10T23:38:00-03:00",
  "rejection_reason": "Motivo da Rejeição",
  "payer": {
    "bank": {
      "account": "12345678",
      "agency": "1234",
      "digit": "9",
      "name": "Banco do Brasil",
      "type": "Conta Corrente"
    },
    "document": "12.345.678/0001-95",
    "name": "Empresa do Henrique"
  },
  "payee": null
}

Webhook Global (via Painel):

{
  "event": "withdrawal.failed",
  "timestamp": "2025-11-10T23:40:00Z",
  "data": {
    "id": 8179,
    "status": "failed",
    "amount": 500,
    "type": "withdrawal",
    "external_id": "MEU-ID-EXTERNO-PAYOUT-789",
    "end_to_end_id": null,
    "created_at": "2025-11-10T23:38:00-03:00",
    "rejection_reason": "Motivo da Rejeição",
    "payer": {
      "bank": {
        "account": "12345678",
        "agency": "1234",
        "digit": "9",
        "name": "Banco do Brasil",
        "type": "Conta Corrente"
      },
      "document": "12.345.678/0001-95",
      "name": "Empresa do Henrique"
    },
    "payee": null
  }
}

📋 Descrição dos Campos

Campo	Tipo	Descrição
`id`	integer	Identificador único do saque (gerado pela API).
`status`	string	Status atual da transação (ex: `"processing"`, `"completed"`, `"failed"`, `"rejected"`).
`amount`	integer	Valor total da transação em centavos (ex: 500 = R$ 5,00).
`type`	string	Tipo da operação (sempre `"withdrawal"` para saques).
`external_id`	string	Identificador externo que será enviado no webhook para facilitar a identificação do repasse no seu sistema.
`end_to_end_id`	string	Identificador End-to-End da transação PIX (disponível após processamento).
`rejection_reason`	string	Motivo da falha ou rejeição (disponível apenas em caso de erro).
`payer`	object	Objeto contendo os dados do pagador (origem do saque).
`payer.bank`	object	Dados bancários do pagador.
`payer.bank.account`	string	Número da conta bancária do pagador.
`payer.bank.agency`	string	Número da agência bancária do pagador.
`payer.bank.digit`	string	Dígito verificador da conta do pagador.
`payer.bank.name`	string	Nome do banco do pagador.
`payer.bank.type`	string	Tipo da conta bancária (ex: `"Conta Corrente"` ou `"Conta Poupança"`).
`payer.document`	string	Documento (CNPJ/CPF) do pagador.
`payer.name`	string	Nome do pagador.
`payee`	object	Objeto contendo os dados do recebedor (destino do saque).
`payee.bank_code`	string	Código do banco do recebedor.
`payee.document`	string	Documento (CNPJ/CPF) do recebedor (pode estar mascarado).
`payee.name`	string	Nome do recebedor.

Campos adicionais no envelope do Webhook Global:

Campo	Tipo	Descrição
`event`	string	Tipo do evento (ex: `"withdrawal.completed"`, `"withdrawal.failed"`).
`timestamp`	string (ISO 8601)	Data/hora em que o evento foi gerado.
`data`	object	Payload do saque (mesmo conteúdo do postback).

🔁 Respondendo a Webhooks

Seu endpoint de webhook deve retornar um código HTTP 2xx (ex: 200, 202, 204) para confirmar o recebimento da notificação.

Se nosso sistema não receber uma resposta 2xx, ele tentará reenviar o webhook até 10 vezes, com intervalos crescentes entre as tentativas (exponential backoff).

🧪 Testando Webhooks

Você pode testar webhooks configurados via painel utilizando o botão Testar na página de Integrações. Ele envia um payload de teste para o seu endpoint sem acionar eventos reais.

🔐 Recomendações de Segurança

1.

Verifique a assinatura — Webhooks configurados via painel incluem o header X-Webhook-Signature com uma assinatura HMAC-SHA256. Valide-a usando o secret fornecido na criação do webhook para garantir que a requisição é legítima.

2.

Implemente tratamento de erros adequado para as requisições recebidas.

3.

Use sempre HTTPS no endpoint do webhook.

4.

Configure monitoramento para acompanhar as entregas e falhas dos webhooks.

💡 Informações Importantes

Os campos payer e payee podem estar null nos eventos iniciais de processing.

O end_to_end_id é o identificador único da transação PIX fornecido pelo Banco Central e só estará disponível durante ou após o processamento.

O rejection_reason fornece detalhes técnicos sobre a falha e está disponível apenas quando o status é failed.

Alguns dados do payee podem estar mascarados por questões de segurança (ex: documento parcialmente oculto).

Precisa de ajuda? Entre em contato com nossa equipe de suporte para desenvolvedores para obter assistência.

Página anterior

Listar Invoices

Próxima página