Pular para o conteúdo principal

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:
  • 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)

Estrutura do objeto decifrado


Exemplo completo de recebimento (Node.js)


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.

Eventos de webhook da loja (API)

A gestão de webhooks (cadastro, listagem e remoção) é feita por loja. Os eventos abaixo são enviados para as URLs cadastradas, com payload criptografado em AES-256-CBC conforme descrito acima.

Implementados atualmente

A plataforma emite 25 eventos cobrindo todo o ciclo de vida dos recursos no padrão recurso.acao:
  • Lojas (4): store.created, store.updated, store.deleted, store.reordered
  • Produtos (4): product.created, product.updated, product.deleted, product.reordered
  • Categorias (4): category.created, category.updated, category.deleted, category.reordered
  • Cupons (4): coupon.created, coupon.updated, coupon.deleted, coupon.reordered
  • Páginas (2): page.upserted, page.deleted
  • Afiliados (3): affiliate.created, affiliate.updated, affiliate.deleted
  • Pagamentos (4): payment.created, payment.updated, payment.deleted, payment.status.changed
Payload descriptografado (exemplo store.created):
Payload descriptografado (exemplo product.created, payment.status.changed, etc.):
Todos os eventos preservam o payload base (event, storeId, timestamp). Os eventos store.created, store.updated e store.deleted mantêm o campo store para retrocompatibilidade, enquanto os demais recursos e store.reordered utilizam o campo data.

Regras de assinatura

  • events = [] (lista vazia) significa todos os eventos (atuais e novos que forem publicados).
  • Lista explícita recebe apenas os eventos informados; novos eventos não são adicionados automaticamente.
  • Ao cadastrar um webhook, a caBRAPI envia WEBHOOK_TEST; seu endpoint deve responder com status 2xx.