> ## Documentation Index
> Fetch the complete documentation index at: https://developers.holdinglegacy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Como receber e tratar notificações em tempo real sobre transações da Legacy.

A Legacy oferece suporte a Webhooks, mecanismo que envia requisições `HTTP POST` diretamente para a sua aplicação toda vez que ocorre uma mudança de evento importante em nossa infraestrutura.

Por exemplo, você pode receber um alerta sempre que:

* O pagamento de um `PIX` for aprovado pelo banco.
* Um saque (`Payout`) finalizar com sucesso.
* Um pagamento por Cartão de Crédito virar Chargeback.

## Onde configurar

Durante as requisições, por exemplo na criação de um Payback `POST /payin`, você envidará nativamente a propriedade `webhookUrl`. A Legacy enviará todas as atualizações pertencentes àquele pagamento para a URL informada dinamicamente.

## Validação e Eventos (Payins)

Quando a Legacy enviar um webhook do Payin, nós usaremos o seguinte **Payload**:

```json theme={null}
{
  "id": "payin_12345",
  "status": "APPROVED",
  "paymentMethod": "PIX",
  "amount": 10000,
  "referenceId": "meu-pedido-1234",
  "customer": {
    "name": "Maria Silva",
    "email": "maria@email.com"
  },
  "updatedAt": "2026-03-02T12:00:00.000Z"
}
```

### Possíveis Status do Payin

É aconselhável que o seu sistema saiba lidar de forma fluida com estes retornos:

* `PENDING` - Gerado, aguardando liquidação.
* `APPROVED` - O saldo está disponível para a loja.
* `FAILED` - Falha catastrófica (Ex: Adquirente fora do ar).
* `CANCELED` - A transação foi cancelada antes de ocorrer.
* `REFUSED` - Saldo negado pelo emissor do Cartão ou sistema Anti-Fraudes.
* `REFUNDED` - Você aplicou um estorno parcial/total na mesma.
* `CHARGEBACK` - Seu cliente contestou com o banco emissor o uso indevido da compra.
* `MED` - Seu cliente contestou com o banco emissor o uso indevido da compra.
* `EXPIRED` - Janela de PIX ou Boleto vencidas.

## Validação e Eventos (Payouts)

Para o saque manual efetuado via API, `POST /payout`, a estrutura possui o seguinte comportamento de disparos no Webhook:

```json theme={null}
{
  "id": "payout_98765",
  "status": "APPROVED",
  "amount": 50000,
  "pixKey": "maria@email.com",
  "pixKeyType": "EMAIL",
  "referenceId": "saque-afiliado-01",
  "updatedAt": "2026-03-02T12:30:00.000Z"
}
```

*Geralmente, um Payout trafegará pelo status `PROCESSING` até consolidar-se em* `APPROVED `*ou `FAILED`.*

***

<Tip>
  Sempre retorne qualquer status HTTP no range `2xx` (Ex: `200 OK`) nos seus controladores de webhook. Se nosso endpoint falhar, tentaremos despachar novamente em janelas crescentes de repetição.
</Tip>