Notificações

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.

​

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: A lista completa de eventos e os schemas de payload estão na Referência de webhooks.

​

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

Um setup típico se apoia em e-mail/WhatsApp automáticos para consciência e em webhooks para reconciliação no nível do ERP.