Business OS · Documentação

#Início rápido

Esta página explica, do zero, como receber os avisos que o Business OS envia quando algo acontece (um pagamento aprovado, um reembolso, um acesso que acabou). Você não precisa saber nada de antemão.

#O que é um webhook

Um webhook é um aviso que nós enviamos para você. Você não precisa ficar perguntando "aconteceu algo?". Quando algo acontece, o Business OS faz um POST na URL que você cadastrou, com os dados em JSON no corpo. Pense no carteiro: você deixa o endereço da caixa de correio e ele entrega.

Do seu lado, você precisa de uma URL pública em https que:

  1. receba um POST com JSON;
  2. confira a assinatura (para saber que o aviso é nosso);
  3. responda 2xx (por exemplo 200) o mais rápido possível;
  4. faça o trabalho de verdade (liberar acesso, atualizar cadastro) depois de responder, ou de forma rápida e segura de repetir.

#O caminho mais curto

  1. Peça à KB. Você não cadastra nada sozinho: não existe API de cadastro, a KB configura o destino para você. Mande a ela a URL https que vai receber os avisos e peça de volta:
    • o segredo whsec_… do seu destino, mostrado uma única vez; guarde em variável de ambiente, nunca no código;
    • a inclusão do host da sua URL na lista de destinos permitidos (sem isso nada é enviado);
    • um token de leitura, se quiser consultar tentativas e fila pela API. O endereço da API é https://api.<domínio>; a KB informa o domínio real.
  2. Crie a rota. Veja o exemplo abaixo.
  3. Confira a assinatura com o código pronto do guia Assinatura e segurança.
  4. Trate o aviso de forma idempotente, ou seja, "se o mesmo aviso chegar duas vezes, o resultado é o mesmo". Veja Entrega, retries e idempotência.
  5. Escolha um fluxo (pagamentos, assinaturas da plataforma, acesso, leads ou grupos) e leia a página dos seus eventos em Webhooks.

#Exemplo mínimo (Node, Express)

const express = require("express");
const { verifyWebhook } = require("./verify"); // veja o guia de assinatura
const app = express();

// IMPORTANTE: express.raw guarda o corpo CRU. A assinatura é calculada sobre os bytes exatos.
app.post("/webhooks/kb", express.raw({ type: "application/json" }), (req, res) => {
  try {
    verifyWebhook(process.env.KB_WEBHOOK_SECRET, req.body, req.headers);
  } catch (e) {
    return res.status(400).send("assinatura inválida"); // 4xx: não vamos tratar este aviso
  }

  const event = JSON.parse(req.body.toString("utf8"));
  const eventId = req.headers["webhook-id"];

  // Idempotência: se já vimos este id, só confirme.
  if (alreadyProcessed(eventId)) return res.status(200).send("ok");

  enqueue(event, eventId); // faz o trabalho depois; responda já
  res.status(200).send("ok");
});

alreadyProcessed e enqueue são funções suas. O ponto central: responda 2xx rápido (o limite é 15 segundos) e guarde o id do aviso para reconhecer repetições.

#Como é um aviso por dentro

Há duas formas de corpo, conforme o fluxo:

Nas duas formas o delivery fica no fim do corpo.

#Envelope de venda e acesso

O exemplo abaixo é de payment.approved, com dados fictícios e abreviado:

{
  "id": "evt_d95a57aef55085517182d986",
  "version": 1,
  "type": "payment.approved",
  "timestamp": "2026-10-15T13:14:43.800Z",
  "occurred_at": "2026-10-15T13:14:42.000Z",
  "environment": "prod",
  "source": { "provider": "cakto", "external_id": "6f1d2c3b-..." },
  "subject": { "type": "payment", "id": "cakto:6f1d2c3b-...", "sequence": 2 },
  "data": {
    "object": { "status": "approved", "amount": 199700, "currency": "BRL", "...": "o pagamento completo" },
    "previous": { "status": "pending" }
  },
  "delivery": {
    "message_id": "evt_d95a57aef55085517182d986",
    "attempt": 1,
    "attempt_id": "3f0c7a52-9b1e-4d6a-8c21-5e7f9a0b1c2d",
    "kind": "first",
    "first_sent_at": null,
    "sale_key": "cakto:6f1d2c3b-...",
    "fact_key": "sale:cakto:6f1d2c3b-...:payment.approved",
    "endpoint_id": "b8e1d4c6-2a3f-4f50-9e7d-1c2b3a4d5e6f"
  }
}

#Corpo plano de lead e grupo

Exemplo de lead.registered, fictício e abreviado:

{
  "schema_version": 1,
  "type": "lead.registered",
  "event_id": "evt_lead_8a1c...",
  "occurred_at": "2026-10-15T13:14:42.000Z",
  "campaign": "...",
  "email": "pessoa@cliente-exemplo.com.br",
  "...": "demais campos do lead",
  "delivery": { "message_id": "...", "attempt": 1, "kind": "first", "...": "como acima" }
}

Aqui event_id identifica o fato; para não repetir trabalho, continue usando o webhook-id (igual a delivery.message_id). O campo is_test fica no topo e só aparece quando vale true; se não estiver no corpo, não é teste.

A página de cada evento em Webhooks mostra o corpo completo, campo a campo, com exemplo.

#O que NÃO fazer

Se algo der errado, a página Porém e erros comuns lista os tropeços mais frequentes.


Assinatura e segurança →