A Caratuva expõe eventos relevantes por alguns canais:
- No produto — uma caixa de entrada por usuário atrás do sino no painel, mais um log de entregas de Notificações.
- E-mail — e-mails transacionais automáticos para os principais eventos de ciclo de vida.
- WhatsApp — alertas de liquidação para o telefone do vendedor, quando há um cadastrado.
- Webhooks de saída — callbacks HTTP assinados para o seu ERP fazer reconciliação máquina a máquina.
Hoje não há preferências de notificação por usuário — as mensagens transacionais são orientadas a eventos, com destinatários derivados da fatura/evento em vez de configurados. Para o contrato de webhook e a verificação de assinatura, veja a Referência de webhooks.
Notificações no produto
O sino na barra superior do painel abre uma caixa de entrada por usuário (com tecnologia do Courier) mostrando seus alertas não lidos; o estado lido/não lido é por usuário, então dois colegas na mesma organização mantêm estados de leitura independentes. Não há controles nativos de filtrar-por-tipo ou limpar-tudo além do que o próprio widget da caixa de entrada oferece.
Separadamente, a página de Notificações (/notifications) é um log de entregas somente leitura de toda mensagem que esta organização despachou — com seu canal, template, destinatário, status e referência — filtrável por canal, status e intervalo de datas. É o lugar para verificar se um convite ao comprador realmente saiu e responder “o cliente recebeu o link?”.
Notificações por e-mail
A Caratuva envia automaticamente e-mails transacionais para eventos específicos de ciclo de vida — por exemplo KYC do comprador aprovado/rejeitado, comprador convidado, fiat recebido, confirmado on-chain, liquidado e off-ramp falhado. Os destinatários são derivados da fatura/evento (o comprador ou o vendedor, conforme apropriado); não há toggles por evento, horário silencioso, agrupamento em resumo nem configurações de opt-in por papel.
Os e-mails são enviados de no-reply@caratuva.com — adicione esse endereço à sua lista de remetentes seguros para evitar atrasos por filtro de spam.
Hoje não há e-mail de mudança de status de KYB/onboarding — o status de KYB do vendedor é mostrado ao vivo na página de Repasses do painel.
Notificações por WhatsApp
Quando há um número de telefone do vendedor cadastrado, a Caratuva também envia ao vendedor alertas por WhatsApp para eventos da fase de liquidação (fiat recebido, confirmado on-chain, liquidado, off-ramp falhado). Isso é automático e não configurável pela organização. (Templates de SMS existem no catálogo, mas não estão ligados a nenhum fluxo ativo — o magic-link do comprador, por exemplo, é entregue por e-mail.)
Webhooks de saída
Para reconciliação por máquina, cadastre uma URL que recebe callbacks POST nos eventos que importam. Exemplos de casos de uso:
- Marcar o pedido como pago no seu ERP quando uma fatura liquida.
- Mostrar um status de pagamento falho para a equipe de vendas.
- Disparar o fulfillment downstream quando o KYC é aprovado.
Inscrição
No painel, Desenvolvedores → Webhooks. Ou via API — veja a Referência de webhooks.
Você fornece:
- Uma URL (precisa ser HTTPS).
- Uma lista de tipos de evento.
- (Gerado para você) Um segredo de assinatura. Aparece exatamente uma vez na criação — copie imediatamente para o seu cofre de senhas.
Tipos de evento
Dois namespaces paralelos:
payment_intent.* — disparam para faturas criadas via API de integrador. Use estes se você é um ERP/plataforma.invoice.* — disparam para toda fatura (criada via API e via painel). Use estes se sua equipe opera principalmente pelo painel.
Os dois namespaces não são simétricos: invoice.* expõe estados mais granulares (ex.: on_ramp_started, fiat_received, offramp_initiated, offramp_failed) do que payment_intent.*. Inscreva-se em um namespace ou nos dois, conforme a operação da sua equipe.
Os eventos que você quase certamente quer:
| Evento | Por quê |
|---|
*.created | Uma fatura veio à existência. |
*.buyer_kyc_approved | Comprador aprovado no KYC; pagamento iminente. |
*.buyer_kyc_rejected | Comprador reprovado no KYC; esta fatura não será paga. |
*.on_chain_confirmed | Transferência transfronteiriça confirmada na camada de liquidação. |
*.settled | Fundos na sua conta bancária. O grande evento. |
*.failed | Falha terminal. Mostre ou estorne. |
*.cancelled | Cancelado por você, sua equipe ou nossa operação. |
*.expired | Comprador não pagou até o vencimento. |
Garantias de entrega
- A Caratuva tenta entrega imediata, depois reentrega em qualquer resposta não-2xx ou erro de transporte com backoff exponencial: 30s, 2m, 10m, 1h, 6h, 24h. Após sete tentativas a entrega vai para
dead_letter e paramos de tentar.
- Cada entrega carrega um
X-Caratuva-Delivery-Id estável — use como chave de idempotência do seu lado. Replays são inevitáveis; projete para eles.
- Cada entrega carrega um header de assinatura HMAC-SHA256. Sempre verifique contra o corpo bruto da requisição antes de agir. Re-serializar o corpo quebra a assinatura.
- Endpoints precisam responder em até 10 segundos.
Inspecionando entregas
O painel mostra entregas recentes por inscrição, com status (pending, delivered, dead_letter), o status code de resposta upstream e o próximo timestamp de retry. Útil para diagnosticar quedas no endpoint ou divergências de assinatura. Você pode reenviar manualmente qualquer entrega pelo painel.
Girando o segredo
Se o segredo de webhook vazar, gire em Desenvolvedores → Webhooks → [inscrição] → Girar segredo. O novo segredo aparece uma vez.
A rotação é imediata e atômica — a Caratuva armazena um único segredo por inscrição, então o antigo deixa de validar já na próxima entrega; não há janela de sobreposição de dois segredos. Implante o novo segredo no seu verificador primeiro (ou atomicamente com a chamada de rotação).
Escolhendo um canal
| Caso de uso | Canal |
|---|
| Você quer confirmar que um convite ao comprador realmente saiu | No produto (o log de entregas de Notificações) |
| Comprador/vendedor precisam de um aviso sobre um evento de ciclo de vida | E-mail (enviado automaticamente) |
| Vendedor quer um aviso de liquidação no celular | WhatsApp (quando há um telefone cadastrado) |
| Financeiro precisa marcar pedidos como pagos no ERP | Webhook |
| Compliance precisa de uma trilha imutável | Webhook (e o log de auditoria) |