#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:
- receba um
POSTcom JSON; - confira a assinatura (para saber que o aviso é nosso);
- responda 2xx (por exemplo
200) o mais rápido possível; - 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
- 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.
- o segredo
- Crie a rota. Veja o exemplo abaixo.
- Confira a assinatura com o código pronto do guia Assinatura e segurança.
- 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.
- 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:
- Vendas, assinaturas da plataforma e acesso (
payment.*,subscription.*,access.*e os demais desses fluxos) usam o envelope comsubjectedata.object, mostrado logo abaixo. Esquema de cada evento: Webhooks. - Leads e grupos (
lead.registered,group.*) têm um corpo plano:schema_version,event_id,type,occurred_ate os dados do fato no topo, semsubjectnemdata.object. Esquema: eventoslead.registeredegroup.*em Webhooks.
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"
}
}
ididentifica o aviso (é o mesmo valor do cabeçalhowebhook-id).versioné a versão do contrato.typediz o que aconteceu. Use-o para decidir o que fazer.occurred_até quando o fato aconteceu;timestampé quando o Business OS o registrou.subjectdiz de qual recurso o aviso fala, esubject.sequencecresce a cada mudança dele.data.objecté o recurso afetado (pagamento, assinatura ou acesso);data.previoustraz o que mudou (por exemplo o status anterior), quando houver.environmentéprodoutest.deliveryé o "recibo de entrega": traz o id do aviso, o número e o id da tentativa, o destino (endpoint_id) e o motivo do envio.
#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
- Não use o objeto já convertido do seu framework para conferir a assinatura (veja "corpo cru").
- Não presuma que os avisos chegam em ordem.
- Não trate
refund.requestedcomo reembolso (veja Tirar acesso). - Não faça nada pesado antes de responder 2xx.
Se algo der errado, a página Porém e erros comuns lista os tropeços mais frequentes.