Copy page

Webhooks

Catálogo de eventos

A Quyta emite dez eventos, em três famílias. Você escolhe quais receber ao cadastrar a assinatura no painel.

Evento	Quando dispara
customer.created	Um cliente foi criado.
debt.created	Uma dívida foi criada.
debt.held	A cobrança de uma dívida foi pausada.
debt.reactivated	A cobrança foi reativada.
debt.archived	A dívida foi arquivada.
debt.unarchived	A dívida foi desarquivada.
contract.created	Um acordo foi fechado.
contract.installment.paid	Uma parcela do acordo foi paga.
contract.settled	O acordo foi integralmente pago.
contract.terminated	O acordo foi quebrado.

Se você só puder consumir dois, consuma contract.created e contract.installment.paid: são os que movem dinheiro.

Todos os exemplos abaixo mostram apenas o campo data. Ele vem sempre dentro do payload padrão.

---

Eventos de cliente

customer.created

Um novo devedor entrou na base — seja por POST /customers, seja por cadastro feito no painel.

Code
{
  "customer": {
    "id": 42,
    "name": "Fulano de Tal",
    "document": "12345678909",
    "emails": [{ "id": 1, "email": "fulano@example.com" }],
    "phones": [{ "id": 1, "phone": "+5511999999999" }]
  },
  "business_unit": { "id": 1, "name": "Empresa Exemplo" }
}

Use quando você precisa espelhar a base de devedores da Quyta no seu CRM. Se todos os clientes nascem do seu próprio sistema via API, esse evento tende a ser redundante — você já sabe da criação pela resposta do POST.

---

Eventos de dívida

debt.created

Uma dívida entrou na carteira. É o evento mais completo: traz a dívida, o devedor, o grupo e a conta numa única entrega.

Code
{
  "debt": {
    "id": 3120,
    "description": "Parcela 05/2026 — contrato 88213",
    "status": "PENDING",
    "original_value": 1000.0,
    "today_value": 1078.5,
    "due_date": "2026-05-15T00:00:00.000000Z",
    "origin_date": "2026-04-15",
    "external_id": "TIT-88213",
    "created_at": "2026-08-27T10:31:00Z",
    "updated_at": "2026-08-27T10:31:00Z"
  },
  "customer": {
    "id": 42,
    "name": "Fulano de Tal",
    "document": "12345678909",
    "emails": [{ "id": 1, "email": "fulano@example.com" }],
    "phones": [{ "id": 1, "phone": "+5511999999999" }]
  },
  "debt_group": { "id": 1, "name": "Carteira principal — 30 a 90 dias" },
  "business_unit": { "id": 1, "name": "Empresa Exemplo" }
}

Use quando dívidas podem ser criadas fora do seu sistema — importação por planilha ou cadastro manual no painel — e você precisa saber disso. O external_id permite casar o evento com o título na sua base.

debt.held

A cobrança foi pausada. A dívida continua existindo, mas a régua para de disparar. Acontece, por exemplo, quando o devedor contesta o débito ou paga fora da Quyta.

Code
{ "debt": { "status": "ON_HOLD" } }

debt.reactivated

A cobrança pausada voltou a rodar. A dívida retorna para PENDING e a régua recomeça.

debt.archived

A dívida saiu do fluxo de cobrança de vez, mantida apenas para histórico — prescrição, baixa contábil, acordo judicial.

Code
{ "debt": { "status": "ARCHIVED" } }

Use para dar baixa na expectativa de recebimento do seu lado. Uma dívida arquivada não será mais cobrada.

debt.unarchived

A dívida foi retirada do arquivo e devolvida ao fluxo de cobrança.

Code
{ "debt": { "status": "PENDING" } }

---

Eventos de acordo

contract.created

O evento mais importante da API. Um acordo foi fechado: o devedor negociou e se comprometeu com um parcelamento. Traz o acordo, todas as parcelas previstas e as dívidas que ele cobre.

Code
{
  "contract": {
    "id": 501,
    "description": "Acordo de renegociação",
    "status": "ACTIVE",
    "value": 5000.0,
    "discount": 500.0,
    "created_at": "2026-09-01T09:12:00Z",
    "updated_at": "2026-09-01T09:12:00Z"
  },
  "installments": [
    { "value": 1000.0, "status": "PENDING", "due_date": "2026-10-01T00:00:00.000000Z" },
    { "value": 1000.0, "status": "PENDING", "due_date": "2026-11-01T00:00:00.000000Z" }
  ],
  "debts": [
    { "id": 3120, "description": "Parcela 05/2026 — contrato 88213", "status": "UNDER_CONTRACT" }
  ]
}

Use para registrar a expectativa de recebimento no seu financeiro e marcar as dívidas como negociadas. O discount é o valor abatido na negociação — informação que costuma interessar ao seu controle de perdas.

Um acordo em DEBT_CONFESSION_PENDING ainda aguarda a assinatura da confissão de dívida: o compromisso existe, mas não está formalizado.

contract.installment.paid

Uma parcela foi paga. É este o evento que representa dinheiro entrando.

Code
{
  "installment_paid": {
    "id": 8801,
    "value": 1000.0,
    "status": "PAID",
    "due_date": "2026-10-01T00:00:00.000000Z",
    "paid_at": "2026-09-28T16:44:12.000000Z"
  }
}

Use para conciliação financeira. O campo paid_at é a data efetiva do pagamento e costuma diferir do due_date — para regime de caixa, use paid_at.

contract.settled

Todas as parcelas do acordo foram pagas. O acordo se encerra e as dívidas cobertas por ele passam a SETTLED.

Code
{
  "contract": { "status": "SETTLED" },
  "installments": [{ "status": "PAID" }],
  "debts": [{ "status": "SETTLED" }]
}

Use para encerrar o caso: a recuperação daquele título terminou com sucesso.

contract.terminated

O acordo foi quebrado — em geral por parcelas em atraso além do tolerado. As dívidas saem de UNDER_CONTRACT, voltam a PENDING e retornam à régua de cobrança.

Code
{ "contract": { "status": "TERMINATED" } }

Use para reverter, no seu financeiro, a expectativa de recebimento registrada em contract.created. Sem tratar este evento, sua previsão de caixa fica otimista demais.

---

O ciclo completo

Próximos passos

• Entrega e retentativas — o que acontece quando seu endpoint falha.
• Segurança — validando a assinatura das entregas.