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

# Webhooks

> Eventos assinados enviados pelo Svix.

Webhooks enviam eventos ao seu servidor assim que acontecem, sem você precisar fazer polling.

## Registrar um endpoint

No painel: **Configurações → API & Webhooks**. Ou pela API, com uma API key que tenha o escopo `webhooks:write`:

```bash theme={null}
curl -X POST "https://api.payable.run/api/v1/developer/webhook-endpoints" \
  -H "Authorization: Bearer esk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.seudominio.com/webhooks/payable",
    "description": "Produção"
  }'
```

## Verificar a assinatura

As entregas são assinadas com o [Svix](https://svix.com). Sempre verifique antes de confiar no payload:

```typescript theme={null}
import { Webhook } from 'svix';

const wh = new Webhook(process.env.PAYABLE_WEBHOOK_SECRET!);
const event = wh.verify(payload, {
  'svix-id': headers['svix-id'],
  'svix-timestamp': headers['svix-timestamp'],
  'svix-signature': headers['svix-signature'],
});
```

Passe o **corpo bruto da requisição** como `payload`, não um JSON reserializado. Responda `2xx` rápido e faça o trabalho pesado de forma assíncrona; entregas que falham são reenviadas.

Endpoints de webhook exigem uma organização em **produção**. Enquanto a organização estiver em modo teste, registrar um endpoint responde `403` com o código `PRODUCTION_REQUIRED` e nenhum evento é enviado; listar e remover endpoints continua funcionando.

O Payable não segue redirecionamentos. Uma resposta `3xx` do seu endpoint é tratada como entrega com falha e reenviada como qualquer outra falha; cadastre a URL final, não uma que redirecione.

## Eventos

| Evento | Quando |
| - | - |
| `client.created` | Um cliente é criado |
| `debt.created` | Uma cobrança é criada |
| `debt.updated` | Uma cobrança muda |
| `debt.paid` | Uma cobrança é quitada |
| `collection.enrollment.started` | Uma cobrança entra na régua |
| `collection.step.executed` | Uma etapa da régua foi executada |
| `payment.received` | Um pagamento foi recebido |
| `message.delivered` | Uma mensagem de WhatsApp foi entregue |
| `voice_call.completed` | Uma ligação de cobrança com IA terminou (veja [Ligações com IA](https://docs.payable.run/pt-BR/voice-calls.md)) |
| `success_fee.created` | A Payable registrou a taxa de êxito sobre um recebimento (só no faturamento por êxito) |

## Payload

```json theme={null}
{
  "id": "evt_uuid",
  "type": "debt.paid",
  "live": true,
  "createdAt": "2026-03-01T12:00:00.000Z",
  "data": {
    "id": "debt_uuid",
    "clientId": "client_uuid",
    "amount": "150.00"
  }
}
```

`live` é `true` para dados de produção e `false` para sandbox. Eventos podem ser entregues mais de uma vez, então deduplique pelo `id`.

### `success_fee.created`

Enviado quando a Payable registra a taxa de êxito sobre um recebimento: a quitação de uma cobrança ou a parcela paga de um acordo, por qualquer meio de pagamento, entre o primeiro envio da régua e o fim da janela de atribuição depois do último. Só organizações faturadas por êxito recebem este evento. Há uma taxa por recebimento, então `data.id` é estável entre reenvios.

```json theme={null}
{
  "id": "evt_uuid",
  "type": "success_fee.created",
  "live": true,
  "createdAt": "2026-10-20T12:00:00.000Z",
  "data": {
    "id": "success_fee_uuid",
    "clientId": "client_uuid",
    "debtId": "debt_uuid",
    "sourceType": "settlement",
    "kind": "recovery",
    "recoveredCents": 30000,
    "feeCents": 3000,
    "feeBps": 1000,
    "collectionMethod": "split",
    "status": "collected"
  }
}
```

| Campo | Descrição |
| - | - |
| `id` | Id da taxa de êxito |
| `clientId` | Cliente que pagou |
| `debtId` | Cobrança a que a taxa pertence. `null` quando `sourceType` é `installment` |
| `sourceType` | `settlement` (cobrança quitada), `installment` (parcela de acordo paga) ou `deletion_review` (cobrança excluída depois de o cliente interagir, aprovada pela Payable) |
| `kind` | `billing_fixed` (taxa fixa por cobrança recebida na Cobrança, `feeBps` = 0) ou `recovery` (percentual sobre o recuperado na Recuperação, e toda taxa registrada antes do lançamento do preço novo). Veja [Recuperação](https://docs.payable.run/pt-BR/recovery.md) |
| `recoveredCents` | Valor sobre o qual a taxa incide, em centavos. Na quitação, desconta o que já foi tarifado nas parcelas da mesma cobrança |
| `feeCents` | Taxa em centavos. Em `recovery`, `recoveredCents × feeBps / 10000`, arredondada para cima a partir da metade; em `billing_fixed`, o valor fixo, nunca mais que o valor pago |
| `feeBps` | Taxa em pontos-base (`1000` = 10%) |
| `collectionMethod` | Como a taxa é cobrada: `split` (retida no próprio pagamento), `custody` (retida no repasse), `wallet` (debitada do seu saldo na Payable) ou `none` |
| `status` | Situação da taxa, por exemplo `collected`, `charged`, `pending_custody`, `withheld`, `waived` ou `review` |


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