Webhooks - API de Pix Out (Withdrawals)

Configuração

Para receber webhooks, você deve fornecer o campo postbackUrl ao criar um saque através da API:

{
    "pixkeytype": "CPF",
    "pixkey": "99999999999",
    "requestedamount": 254,
    "description": "Saque via API",
    "isPix": true,
    "postbackUrl": "https://seu-dominio.com/webhook/withdrawals"
}

Requisitos do Endpoint

Seu endpoint de webhook deve:

✅ Aceitar requisições POST

✅ Responder com status HTTP 200 para confirmar recebimento

✅ Processar o payload JSON enviado no body

✅ Responder em até 30 segundos

✅ Usar HTTPS (recomendado para segurança)

Eventos Disponíveis

📋 Lista de Eventos

Evento	Descrição	Quando é enviado
`withdrawal.created`	Saque criado com sucesso	Imediatamente após criação bem-sucedida
`withdrawal.status_changed`	Status do saque foi alterado	Quando há mudança de status (ex: pending → approved)
`withdrawal.completed`	Saque foi concluído	Quando o saque é finalizado com sucesso
`withdrawal.failed`	Saque falhou	Quando o saque falha ou é cancelado

🔄 Fluxo Típico de Eventos

Exemplo de sequência:

withdrawal.created - Status: pending

withdrawal.status_changed - Status: approved

withdrawal.status_changed - Status: processing

withdrawal.completed - Status: done

Status de Saques

📊 Todos os Status Possíveis

Status	Descrição	Evento Típico
`pending`	Aguardando aprovação manual	`withdrawal.created`
`approved`	Aprovado para processamento	`withdrawal.status_changed`
`processing`	Em processamento pelo BaaS	`withdrawal.status_changed`
`done`	Concluído automaticamente	`withdrawal.completed`
`done_manual`	Concluído manualmente	`withdrawal.completed`
`failed`	Falhou durante processamento	`withdrawal.failed`
`refused`	Recusado na aprovação	`withdrawal.failed`
`cancelled`	Cancelado pelo sistema	`withdrawal.failed`

🔀 Transições de Status

pending → approved → processing → done
pending → refused
approved → failed
processing → failed
pending → cancelled

Formato do Payload

Estrutura Base

Todos os webhooks seguem a mesma estrutura base:

{
    "event": "withdrawal.created",
    "timestamp": "2025-07-10T17:40:27.373Z",
    "withdrawal": {
        // Dados completos do saque
    },
    "metadata": {
        "source": "withdrawals_service",
        "version": "1.0.0"
    }
}

Objeto Withdrawal

{
    "id": "756d4eec-9a22-44b0-a514-a27c366c5433",
    "company_id": "5e1ce642-b9f1-433c-a350-5f9cd3d16bf6",
    "requested_amount": 2.54,
    "currency": "BRL",
    "status": "pending",
    "created_at": "2025-07-10T14:40:26.270543",
    "updated_at": "2025-07-10T14:40:26.270543",
    "paid_at": null,
    "pix": {
        "key_type": "CPF",
        "key_value": "99999999999",
        "end_to_end_id": null
    },
    "fee": 0,
    "net_amount": 2.54,
    "error_message": null
}

Exemplos de Webhooks

1. withdrawal.created

Enviado quando um saque é criado com sucesso.

{
    "event": "withdrawal.created",
    "timestamp": "2025-07-10T17:40:27.373Z",
    "withdrawal": {
        "id": "756d4eec-9a22-44b0-a514-a27c366c5433",
        "company_id": "5e1ce642-b9f1-433c-a350-5f9cd3d16bf6",
        "requested_amount": 2.54,
        "currency": "BRL",
        "status": "pending",
        "created_at": "2025-07-10T14:40:26.270543",
        "updated_at": "2025-07-10T14:40:26.270543",
        "paid_at": null,
        "pix": {
            "key_type": "CPF",
            "key_value": "99999999999",
            "end_to_end_id": null
        },
        "fee": 0,
        "net_amount": 2.54,
        "error_message": null
    },
    "metadata": {
        "source": "withdrawals_service",
        "version": "1.0.0"
    }
}

2. withdrawal.status_changed

Enviado quando o status de um saque é alterado.

{
    "event": "withdrawal.status_changed",
    "timestamp": "2025-07-10T17:45:12.123Z",
    "withdrawal": {
        "id": "756d4eec-9a22-44b0-a514-a27c366c5433",
        "company_id": "5e1ce642-b9f1-433c-a350-5f9cd3d16bf6",
        "requested_amount": 2.54,
        "currency": "BRL",
        "status": "approved",
        "created_at": "2025-07-10T14:40:26.270543",
        "updated_at": "2025-07-10T17:45:12.100000",
        "paid_at": null,
        "pix": {
            "key_type": "CPF",
            "key_value": "99999999999",
            "end_to_end_id": null
        },
        "fee": 0,
        "net_amount": 2.54,
        "error_message": null
    },
    "metadata": {
        "source": "withdrawals_service",
        "version": "1.0.0"
    }
}

3. withdrawal.completed

Enviado quando um saque é concluído com sucesso.

{
    "event": "withdrawal.completed",
    "timestamp": "2025-07-10T18:15:45.456Z",
    "withdrawal": {
        "id": "756d4eec-9a22-44b0-a514-a27c366c5433",
        "company_id": "5e1ce642-b9f1-433c-a350-5f9cd3d16bf6",
        "requested_amount": 2.54,
        "currency": "BRL",
        "status": "done",
        "created_at": "2025-07-10T14:40:26.270543",
        "updated_at": "2025-07-10T18:15:45.400000",
        "paid_at": "2025-07-10T18:15:45.400000",
        "pix": {
            "key_type": "CPF",
            "key_value": "99999999999",
            "end_to_end_id": "E1234567890123456789012345678901"
        },
        "fee": 0,
        "net_amount": 2.54,
        "error_message": null
    },
    "metadata": {
        "source": "withdrawals_service",
        "version": "1.0.0"
    }
}

4. withdrawal.failed

Enviado quando um saque falha ou é cancelado.

{
    "event": "withdrawal.failed",
    "timestamp": "2025-07-10T18:20:30.789Z",
    "withdrawal": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "company_id": "5e1ce642-b9f1-433c-a350-5f9cd3d16bf6",
        "requested_amount": 100.0,
        "currency": "BRL",
        "status": "failed",
        "created_at": "2025-07-10T18:10:15.123456",
        "updated_at": "2025-07-10T18:20:30.750000",
        "paid_at": null,
        "pix": {
            "key_type": "EMAIL",
            "key_value": "usuario@exemplo.com",
            "end_to_end_id": null
        },
        "fee": 2.5,
        "net_amount": 97.5,
        "error_message": "Chave PIX não encontrada no sistema do banco"
    },
    "metadata": {
        "source": "withdrawals_service",
        "version": "1.0.0"
    }
}

Implementação

Exemplo básico (Node.js/Express)

Exemplo com validação (Python/Flask)

Política de Retry

Como funciona

Tentativas: Até 3 tentativas de entrega

Intervalos: 1 minuto, 5 minutos, 15 minutos

Condição para retry: Status HTTP diferente de 200

Timeout: 30 segundos por tentativa

Sequência de retry

Tentativa 1: Imediato
   ↓ (falha)
Tentativa 2: +1 minuto
   ↓ (falha)
Tentativa 3: +5 minutos
   ↓ (falha)
Tentativa 4: +15 minutos
   ↓ (falha)
Webhook descartado

Evitando retries desnecessários

Segurança

Validações Recomendadas

Validar origem: Verifique se a requisição vem de IPs confiáveis

Validar estrutura: Confirme que o payload tem a estrutura esperada

Rate limiting: Implemente rate limiting no seu endpoint

Logs de auditoria: Registre todos os webhooks recebidos

Exemplo de validação de origem

Debugging e Monitoramento

Logs Importantes

Métricas Úteis

Taxa de sucesso: % de webhooks processados com sucesso

Tempo de resposta: Tempo para responder com status 200

Eventos por tipo: Distribuição dos tipos de evento

Retries: Quantidade de webhooks que precisaram de retry

Ferramentas de Teste

webhook.site - Para testes rápidos

ngrok - Para expor localhost durante desenvolvimento

Postman - Para simular webhooks manualmente

Troubleshooting

Problemas Comuns

Problema	Causa	Solução
Webhooks não chegam	URL inacessível	Verificar se URL responde e usa HTTPS
Múltiplos retries	Não responde 200	Sempre responder com status 200
Payloads duplicados	Processamento lento	Implementar idempotência usando withdrawal.id
Timeout	Processamento > 30s	Processar de forma assíncrona

Checklist de Verificação

URL do webhook está acessível publicamente

Endpoint responde com status 200

Tempo de resposta < 30 segundos

Tratamento de erros implementado

Logs de auditoria configurados

Validações de segurança ativas

Processamento idempotente

Suporte

Para dúvidas sobre webhooks ou problemas de integração:

📧 Email: contato@fullpix.com.br

📚 Documentação: https://docs.fullpix.com.br

Última atualização: 07/11/2025

Webhooks

Webhooks - API de Pix Out (Withdrawals)#

Configuração#

Requisitos do Endpoint#

Eventos Disponíveis#

📋 Lista de Eventos#

🔄 Fluxo Típico de Eventos#

Status de Saques#

📊 Todos os Status Possíveis#

🔀 Transições de Status#

Formato do Payload#

Estrutura Base#

Objeto Withdrawal#

Exemplos de Webhooks#

1. withdrawal.created#

2. withdrawal.status_changed#

3. withdrawal.completed#

4. withdrawal.failed#

Implementação#

Exemplo básico (Node.js/Express)#

Exemplo com validação (Python/Flask)#

Política de Retry#

Como funciona#

Sequência de retry#

Evitando retries desnecessários#

Segurança#

Validações Recomendadas#

Exemplo de validação de origem#

Debugging e Monitoramento#

Logs Importantes#

Métricas Úteis#

Ferramentas de Teste#

Troubleshooting#

Problemas Comuns#

Checklist de Verificação#

Suporte#