Webhooks

Webhooks permitem que a Legacy notifique sua aplicação automaticamente sobre mudanças de status em cobranças e saques, sem a necessidade de consultar a API repetidamente.

Sempre que um evento relevante ocorrer — pagamento PIX confirmado, saque concluído, estorno aplicado — a Legacy enviará uma requisição POST para a URL que você informou na criação da transação.

Como configurar

Ao criar um Payin ou Payout, inclua o campo webhookUrl com a URL do seu endpoint:

{
  "paymentMethod": "PIX",
  "amount": 10000,
  "webhookUrl": "https://sua-api.com/webhooks/legacy",
  ...
}

A Legacy enviará todas as atualizações daquela transação específica para essa URL.

📘

Campo opcional, mas altamente recomendado

Sem webhookUrl, você precisará consultar a API manualmente para verificar mudanças de status. O uso de webhooks é a forma mais eficiente e confiável de monitorar suas transações.

Eventos de Payin

Quando o status de um Payin mudar, você receberá um payload como este:

{
  "id": "payin_1A2B3C",
  "status": "APPROVED",
  "paymentMethod": "PIX",
  "amount": 10000,
  "referenceId": "pedido-001",
  "customer": {
    "name": "Maria Silva",
    "email": "[email protected]"
  },
  "updatedAt": "2026-03-02T12:05:00.000Z"
}

Status possíveis do Payin

Eventos de Payout

Quando o status de um Payout mudar, você receberá:

{
  "id": "payout_1A2B3C",
  "status": "COMPLETED",
  "amount": 250000,
  "pixKey": "[email protected]",
  "pixKeyType": "EMAIL",
  "referenceId": "comissao-001",
  "updatedAt": "2026-03-02T12:30:00.000Z"
}

Status possíveis do Payout

Política de resposta e reenvio

👍

Responda com status 2xx para confirmar o recebimento

Qualquer status HTTP no range 200–299 é aceito como confirmação. Não é necessário nenhum corpo de resposta específico.

Se o seu endpoint retornar um erro (status 4xx ou 5xx) ou não responder dentro do tempo limite, a Legacy tentará reenviar o evento em intervalos crescentes:

🚧

Projete seu endpoint para ser idempotente

Como um mesmo evento pode ser entregue mais de uma vez em caso de falha, use o campo id da transação para garantir que você não processe o mesmo evento duas vezes.