Webhooks

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:

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. Sempre verifique antes de confiar no payload:

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)
`success_fee.created`	A Payable registrou a taxa de êxito sobre um recebimento (só no faturamento por êxito)

Payload

{
  "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.

{
  "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
`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`

Começar

Integração

Referência da API

Registrar um endpoint

Verificar a assinatura

Eventos

Payload

`success_fee.created`

​Registrar um endpoint

​Verificar a assinatura

​Eventos

​Payload

​success_fee.created

Registrar um endpoint

Verificar a assinatura

Eventos

Payload

`success_fee.created`