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 campopayload 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
- 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 status2xx. - 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ãorecurso.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
store.created):
product.created, payment.status.changed, etc.):
Todos os eventos preservam o payload base (event,storeId,timestamp). Os eventosstore.created,store.updatedestore.deletedmantêm o campostorepara retrocompatibilidade, enquanto os demais recursos estore.reorderedutilizam o campodata.
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 status2xx.