📌 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
}

Campo	Tipo	Descrição
`event`	`string`	Sempre `PAYMENT_STATUS_UPDATE`
`uuid`	`string`	UUID do pagamento
`status`	`string`	`APPROVED`, `EXPIRED`, `REJECTED` ou `PENDING`
`storeId`	`string`	ID da loja que originou o evento
`timestamp`	`number`	Timestamp 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

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

Geral

Integrações de Pagamento

Webhooks

Webhook

📌 Tutorial em vídeo

O que é um Webhook?

Como funciona na caBRAPI?

Eventos suportados

Como funciona o payload criptografado

Decifrando o payload (Node.js)

Estrutura do objeto decifrado

Exemplo completo de recebimento (Node.js)

Como configurar seu Webhook

Links úteis

​📌 Tutorial em vídeo

​O que é um Webhook?

​Como funciona na caBRAPI?

​Eventos suportados

​Como funciona o payload criptografado

​Decifrando o payload (Node.js)

​Estrutura do objeto decifrado

​Exemplo completo de recebimento (Node.js)

​Como configurar seu Webhook

​Links úteis

📌 Tutorial em vídeo

O que é um Webhook?

Como funciona na caBRAPI?

Eventos suportados

Como funciona o payload criptografado

Decifrando o payload (Node.js)

Estrutura do objeto decifrado

Exemplo completo de recebimento (Node.js)

Como configurar seu Webhook

Links úteis