Copy page

Webhooks

Introdução aos webhooks

A cobrança acontece do lado da Quyta: a régua dispara mensagens, o devedor negocia, fecha um acordo, paga uma parcela. Nada disso parte de uma chamada do seu sistema — e por isso seu sistema não teria como saber que aconteceu.

Os webhooks resolvem isso. Você registra uma URL, e a Quyta faz um POST nela sempre que um evento relevante ocorre.

Por que não consultar em laço

A alternativa seria varrer GET /debts de tempos em tempos procurando mudanças. Isso funciona mal por três motivos: consome o limite de requisições, atrasa a informação em até um ciclo inteiro de consulta, e piora conforme a carteira cresce.

Com webhook a informação chega em segundos e o custo não cresce com o tamanho da carteira, e sim com o número de eventos — que é exatamente o que você precisa processar de qualquer forma.

Configurando um endpoint

As assinaturas de webhook são gerenciadas no painel da Quyta. Ao criar uma, você define:

1. A URL que vai receber os POST. Precisa ser HTTPS e acessível publicamente.
2. Os tipos de evento que quer receber — veja o catálogo completo.
3. Um segredo, usado para assinar cada entrega. É opcional, mas recomendado.

O painel também mostra o histórico de entregas de cada assinatura, com o código de resposta que o seu endpoint devolveu — o primeiro lugar a olhar quando algo não chega.

O que o seu endpoint precisa fazer

Quatro requisitos, em ordem de importância:

Responder 2xx rapidamente. Qualquer status entre 200 e 299 marca a entrega como bem-sucedida. Qualquer outra coisa — ou um timeout — é tratada como falha e entra em retentativa.

Não processar de forma síncrona. Valide a assinatura, grave o evento numa fila e responda. Se você processar tudo antes de responder, uma lentidão no seu banco vira timeout de webhook.

Verificar a assinatura antes de confiar no conteúdo. Veja Segurança.

Tolerar repetições. Uma retentativa pode entregar duas vezes o mesmo evento. Use o campo id do payload para descartar duplicatas.

O formato do evento

Todo webhook chega com o mesmo payload:

Code
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "debt.created",
  "version": "1",
  "created_at": "2026-08-27T10:30:00Z",
  "data": { }
}

Campo	Descrição
id	UUID único do evento. Use-o para deduplicação.
type	O tipo do evento — determina o formato de data.
version	Versão do formato do evento. Hoje sempre "1".
created_at	Quando o evento ocorreu, em ISO 8601.
data	O conteúdo, específico de cada tipo de evento.

Ramifique o seu processamento por type e leia data conforme o catálogo de eventos.

Um receptor mínimo

Code
import express from "express";

const app = express();

// Guarde o corpo bruto: a assinatura é calculada sobre ele.
app.post(
  "/webhooks/quyta",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    if (!assinaturaValida(req.body, req.get("Quyta-Webhook-Signature"))) {
      return res.sendStatus(401);
    }

    const evento = JSON.parse(req.body.toString("utf8"));

    // Responda primeiro; processe depois.
    res.sendStatus(200);

    await fila.publicar(evento);
  },
);

app.listen(3000);

A implementação de assinaturaValida está em Segurança.

Próximos passos

• Catálogo de eventos — os dez eventos e o que cada um significa.
• Entrega e retentativas — headers, timeout e política de reenvio.
• Segurança — validação da assinatura HMAC.