Eventos e Webhooks (PIX-OUT)

Os webhooks são notificações HTTP automáticas enviadas pela API de Saques sempre que há mudanças importantes no status de um saque. Eles permitem que seu sistema seja notificado em tempo real sobre eventos relacionados aos saques, eliminando a necessidade de polling constante da API.

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

    A[withdrawal.created] --> B[withdrawal.status_changed]
    B --> C[withdrawal.completed]
    B --> D[withdrawal.failed]

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": "[email protected]",
            "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"
    }
}

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

Suporte

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

📧 Email: [email protected]

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