Skip to main content

​
📌 Tutorial em vídeo

​
O que é um Webhook?

Webhooks permitem que sua loja receba notificações automáticas sempre que um evento importante ocorre, como a aprovação ou expiração de um pagamento. Assim, você pode automatizar processos e integrar sistemas externos facilmente.

​
Como funciona na caBRAPI?

Quando o status de um pagamento muda (por exemplo, aprovado ou expirado), a caBRAPI envia uma requisição HTTP POST para todas as URLs de webhook cadastradas para a loja. Cada loja pode cadastrar múltiplos webhooks, respeitando o limite do plano contratado. O limite máximo é exibido no painel e pode ser consultado via API.

​
Eventos suportados

  • Pagamento aprovado (APPROVED)
  • Pagamento expirado (EXPIRED)

​
Como funciona o payload criptografado

O campo payload enviado para cada webhook é uma string criptografada com AES-256-CBC, no formato: 
<iv_base64>:<encrypted_base64>
  • O IV (vetor de inicialização) e o conteúdo criptografado são separados por dois-pontos.
  • A chave de cifragem é derivada da API Key do dono da loja via SHA-256.
Atenção: Seu endpoint precisa conhecer a API Key do dono da loja para decifrar o payload.

​
Decifrando o payload (Node.js)

import crypto from 'crypto';

function decryptPayload(payload, apiKey) {
  const [ivB64, encryptedB64] = payload.split(":");
  const iv = Buffer.from(ivB64, "base64");
  const encrypted = Buffer.from(encryptedB64, "base64");
  const key = crypto.createHash("sha256").update(apiKey).digest();
  const decipher = crypto.createDecipheriv("aes-256-cbc", key, iv);
  let decrypted = decipher.update(encrypted, undefined, "utf8");
  decrypted += decipher.final("utf8");
  return JSON.parse(decrypted);
}

// Uso:
// const data = decryptPayload(req.body.payload, 'SUA_API_KEY_AQUI');

​
Estrutura do objeto decifrado

{
  "event": "PAYMENT_STATUS_UPDATE",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "status": "APPROVED",
  "storeId": "b1c1b1c1-b1c1-b1c1-b1c1-b1c1b1c1b1c1",
  "timestamp": 1710000000000
}
CampoTipoDescrição
eventstringSempre PAYMENT_STATUS_UPDATE
uuidstringUUID do pagamento
statusstringAPPROVED, EXPIRED, REJECTED ou PENDING
storeIdstringID da loja que originou o evento
timestampnumberTimestamp em milissegundos do momento do envio

​
Exemplo completo de recebimento (Node.js)

import express from 'express';
import crypto from 'crypto';

const app = express();
app.use(express.json());

function decryptPayload(payload, apiKey) {
  const [ivB64, encryptedB64] = payload.split(":");
  const iv = Buffer.from(ivB64, "base64");
  const encrypted = Buffer.from(encryptedB64, "base64");
  const key = crypto.createHash("sha256").update(apiKey).digest();
  const decipher = crypto.createDecipheriv("aes-256-cbc", key, iv);
  let decrypted = decipher.update(encrypted, undefined, "utf8");
  decrypted += decipher.final("utf8");
  return JSON.parse(decrypted);
}

app.post('/meu-webhook', (req, res) => {
  const { payload } = req.body;
  if (!payload) return res.status(400).send('Payload ausente');

  const data = decryptPayload(payload, process.env.API_KEY);
  console.log('Evento recebido:', data);

  if (data.event === 'PAYMENT_STATUS_UPDATE' && data.status === 'APPROVED') {
    // processe o pagamento aprovado aqui
  }

  res.sendStatus(200);
});

app.listen(3000, () => console.log('Webhook ouvindo na porta 3000'));

​
Como configurar seu Webhook

  1. Acesse o painel da sua loja e vá em Configurações → Webhooks.
  2. Adicione uma ou mais URLs — o limite depende do seu plano e é exibido no painel.
  3. Ao cadastrar, a caBRAPI enviará automaticamente um evento de teste (WEBHOOK_TEST) para validar o endpoint. Seu servidor deve responder com status 2xx.
  4. A partir daí, todos os eventos de pagamento serão disparados automaticamente para as URLs cadastradas.