Como criar um webhook

📘 Documentação de Webhooks

Esta documentação descreve todos os webhooks disponíveis para integração, seus respectivos eventos e os payloads JSON simulados enviados pelo sistema em ambiente sandbox para testes.

🧪 Introdução

Cada evento listado aqui pode ser simulado via o [endpoint de sandbox](url do frontend para testar webhooks) e será enviado via requisição HTTP POST para a URL cadastrada pelo usuário. Os dados simulados são realistas, mas fictícios, gerados para facilitar testes e depuração do seu sistema.

🔄 Lista de Eventos Disponíveis

📦 Payloads por Evento

1. 🛒 Carrinho Abandonado – ABANDONED_CART

Evento disparado quando um carrinho é marcado como abandonado.

{
 "cartId": "d02f5214-5e3e-4036-9e0d-f4f94bdcf127",
 "checkoutLink": "https://sua-loja.com/checkout?cartId=d02f5214-5e3e-4036-9e0d-f4f94bdcf127",
 "name": "Lucas Rocha",
 "productId": "b05b7923-2c58-4eec-b86b-4f13c0e8034d",
 "status": "ABANDONED_CART",
 "createdAt": "2025-08-04T12:43:02.123Z",
 "productName": "Curso Completo de JavaScript",
 "document": "479.136.106-70"
}

email e phone podem existir em notificações reais, mas não são preenchidos pelo simulador de carrinho abandonado.

2. ✅ Compra Aprovada – PURCHASE_APPROVED

Evento disparado quando um pagamento é confirmado.

{
 "id": "1a2b3c4d-5678-90ef-gh12-ijklmnop3456",
 "typeOfSale": "PRODUCER",
 "releaseDate": "2025-08-14T12:43:02.123Z",
 "commissions": [
   {
     "customer": { "name": "Maria Oliveira" },
     "releaseDate": "2025-08-14T12:43:02.123Z",
     "status": "AWAITING_PAYMENT",
     "typeOfSale": "PRODUCER",
     "value": 83.27
   }
 ],
 "offer": {
   "id": "offer-id",
   "name": "super promo",
   "product": {
     "id": "product-id",
     "name": "product x"
   }
 },
 "price": 395.00,
 "fee": 19.75,
 "commission": 83.27,
 "netRevenue": 291.98,
 "totalAmount": 498.02,
 "payment": {
   "paymentMethod": "BILLET",
   "generatedPaymentMethod": "BILLET"
 },
 "customer": {
   "name": "João Pedro",
   "email": "joao.pedro@email.com",
   "document": "479.136.106-70"
 },
 "createdAt": "2025-08-04T12:43:02.123Z",
 "updatedAt": "2025-08-04T12:43:02.123Z"
}

3. 💸 Reembolso – REFUND

Enviado quando uma compra é reembolsada.

Payload:

{
 "id": "1a2b3c4d-5678-90ef-gh12-ijklmnop3456",
 "typeOfSale": "PRODUCER",
 "releaseDate": "2025-08-14T12:43:02.123Z",
 "commissions": [...],
 "offer": {...},
 "price": 395.00,
 "fee": 19.75,
 "commission": 83.27,
 "netRevenue": 291.98,
 "totalAmount": 498.02,
 "payment": {
   "paymentMethod": "BILLET",
   "generatedPaymentMethod": "BILLET"
 },
 "customer": {
   "name": "João Pedro",
   "email": "joao.pedro@email.com",
   "document": "479.136.106-70"
 },
 "createdAt": "2025-08-04T12:43:02.123Z",
 "updatedAt": "2025-08-04T12:43:02.123Z",
 "refundPdfUrl": "https://boraup.com.br"
}

4. ⚠️ Chargeback – CHARGEBACK

Disparado quando um pagamento é contestado junto à operadora.

Payload:

Mesmo payload de PURCHASE_APPROVED, com o campo eventType: "CHARGEBACK".

5. 🧾 Boleto Gerado – BILLET_GENERATED

Enviado no momento da geração do boleto bancário.

Payload:

Mesmo payload de PURCHASE_APPROVED, com o campo eventType: “BILLET_GENERATED”; no sandbox, payment.paymentMethod e payment.generatedPaymentMethod são billet.

6. 🔢 PIX Gerado – PIX_GENERATED

Evento que indica que um pagamento com PIX foi criado.

Payload:

Mesmo payload de PURCHASE_APPROVED, com o campo eventType: “PIX_GENERATED”; no sandbox, payment.paymentMethod e payment.generatedPaymentMethod são pix.

7. 🧰 Regras de Negócio Simuladas

• Comissões: Geradas aleatoriamente com valores entre 1% e 15%.
• Taxas: Calculadas com base em taxas de 1% a 10%.
• Datas: releaseDate é sempre 10 dias após a data atual.
• Documentos: CPF fictício, mas com formato válido.

8. 🛡️ Segurança

Todos os webhooks devem ser verificados no seu sistema por meio de:

• Verificação da origem do IP (caso aplicável)
• Conferência do conteúdo JSON recebido
• Verificação de assinatura

8.1. 🛡️ Verificação de assinatura

Cada notificação inclui o cabeçalho Boraup-Signature. Ele contém a assinatura HMAC-SHA256, em hexadecimal, calculada sobre o corpo JSON enviado usando o segredo associado ao webhook.

Para validar a notificação:

1. Leia e preserve o corpo HTTP bruto, antes de convertê-lo em objeto ou reserializá-lo.
2. Calcule o HMAC-SHA256 desse corpo usando o segredo do webhook.
3. Compare a assinatura calculada com Boraup-Signature, ambos devem ser iguais.
4. Rejeite a notificação se a assinatura não corresponder.

O segredo do webhook deve ser mantido privado.

9. Respostas, tentativas e reenvio

Responda rapidamente com um status HTTP 2xx após aceitar a notificação. O sistema considera status abaixo de 300 como sucesso. Em caso de resposta com status 300 ou superior, são programadas novas tentativas de envio com delay exponencial entre elas. As tentativas e respostas ficam disponíveis nos registros de envios do webhook; uma notificação também pode ser reenviada pela tela [de reenvio de webhook](url do frontend pra reenviar a notificação do webhook).

Torne o processamento idempotente: uma mesma notificação pode ser entregue mais de uma vez, por exemplo, após uma falha temporária.

🔄 Recomendações para Integração

• Utilize ferramentas como Webhook.site, RequestBin ou o Postman para testar.
• Armazene logs de cada webhook recebido para análise futura.
• Garanta que seu endpoint responda com HTTP 2xx para confirmar o recebimento.

❓ Dúvidas Frequentes

Posso configurar múltiplos webhooks?
Sim, o sistema permite múltiplas URLs por tipo de evento e por produto.

Posso filtrar por produto?
Sim, em produção o webhook pode ser restrito a produtos específicos.

Como recebo novamente um webhook perdido?
No ambiente de produção, o sistema tentará reenvio em caso de falha. No sandbox, basta executar novamente o teste.

📞 Suporte

Em caso de dúvidas ou problemas na integração, entre em contato com o suporte técnico via:

• Email: suporte@boraup.com.br
• Whatsapp