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

# Payout Webhooks

> O payload enviado ao seu endpoint de webhook quando um payout é criado ou altera de status. Use esses eventos para reconciliar payouts nos seus sistemas contábeis.

> [!NOTE]
>
> Os webhooks de repasse informam quando seus próprios fundos são transferidos da Dodo Payments para sua conta bancária. Use-os para reconciliar repasses em seus sistemas contábeis sem consultar repetidamente o endpoint [List Payouts](https://docs.dodopayments.com/api-reference/payouts/get-payouts.md).

## Eventos de webhook de repasse

Um repasse emite um evento em cada etapa do seu ciclo de vida. As etapas correspondem aos [status de repasse](https://docs.dodopayments.com/features/payouts/payout-structure.md) exibidos no seu dashboard.

| Evento | Ocorre quando | O que isso geralmente significa |
| - | - | - |
| `payout.created` | Um repasse é criado, pelo ciclo automático de repasses ou fora do ciclo | O repasse existe, mas ainda não começou a ser movimentado |
| `payout.in_progress` | A data de vencimento do repasse chega e o processamento começa | Os fundos estão a caminho da sua conta bancária |
| `payout.on_hold` | O repasse é pausado ou colocado em análise | Talvez seja necessário fornecer informações adicionais |
| `payout.success` | O repasse para sua conta bancária é liquidado | Os fundos devem estar disponíveis na sua conta |
| `payout.failed` | O repasse falha | O valor e as tarifas são creditados novamente na sua carteira |

> [!NOTE]
>
> O `payout.created` era emitido anteriormente como `payout.not_initiated`. Se um endpoint existente filtra por `payout.not_initiated`, atualize o filtro para `payout.created` para que ele continue correspondendo. O campo `status` no payload ainda informa `not_initiated` nesta etapa.

## Como lidar com eventos de repasse

Os repasses dizem respeito ao seu próprio dinheiro, e não ao de um cliente, portanto esses eventos geralmente alimentam a escrituração contábil e os alertas internos, em vez de fluxos voltados para o cliente.

```javascript Handling payout events expandable theme={null}
app.post('/webhooks/dodo', async (req, res) => {
  // Verify the signature first. See /developer-resources/webhooks#verifying-signatures.
  // With express.raw(), req.body is a Buffer, so parse it after verification.
  const event = JSON.parse(req.body);

  switch (event.type) {
    case 'payout.created': {
      const payout = event.data;
      // Record the expected payout so finance can reconcile it later
      await recordPayout(payout.payout_id, payout.amount, payout.currency);
      break;
    }
    case 'payout.success': {
      // Funds settled — mark the payout as received
      await markPayoutSettled(event.data.payout_id, event.data.updated_at);
      break;
    }
    case 'payout.failed': {
      // Funds and fees are credited back to your wallet — alert finance
      await alertPayoutFailed(event.data.payout_id, event.data.remarks);
      break;
    }
    case 'payout.on_hold': {
      // Review may be required before the payout can continue
      await alertPayoutOnHold(event.data.payout_id, event.data.remarks);
      break;
    }
  }

  res.json({ received: true });
});
```

> [!TIP]
>
> Sempre verifique a assinatura do webhook antes do processamento — consulte o [guia de Webhooks](https://docs.dodopayments.com/developer-resources/webhooks.md) para obter instruções de configuração. O handler acima omite a verificação por brevidade.

> [!WARNING]
>
> Os eventos de payout não são terminais nem estritamente ordenados. `payout.failed` pode chegar depois de `payout.success` quando um banco devolve a transferência, e `payout.success` pode chegar depois de `payout.failed` quando um payout com falha é recuperado posteriormente. O `status` do payload sempre corresponde ao tipo de evento, mesmo quando o evento é entregue com atraso; portanto, compare o `timestamp` de nível superior de cada evento com o último que você processou para esse payout, em vez de presumir que o último evento recebido é definitivo.

## Status do repasse

O objeto de repasse informa seu progresso por meio de um único campo:

| Campo | Valores |
| - | - |
| `status` | `not_initiated`, `in_progress`, `on_hold`, `success`, `failed` |

> [!NOTE]
>
> `refunds`, `chargebacks` e `tax` no payload estão obsoletos. Use os [endpoints de detalhamento de repasse](https://docs.dodopayments.com/api-reference/payouts/retrieve-breakup.md) para obter um detalhamento completo.

## Relacionado

> [card] [Payout Structure](https://docs.dodopayments.com/features/payouts/payout-structure.md)
>
> Como os repasses são programados e calculados, e o que cada status de repasse significa.

> [card] [Balances & Wallets](https://docs.dodopayments.com/features/account-summary-payout-wallet.md)
>
> Acompanhe os saldos da carteira e o ledger por trás de cada repasse.

## Esquema do payload do webhook


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.