> ## Documentation Index > Fetch the complete documentation index at: https://docs.caratuva.com/llms.txt > Use this file to discover all available pages before exploring further. # Notificações > Como a Caratuva avisa o que aconteceu — no produto, por e-mail e WhatsApp, e via webhooks. 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](/pt-BR/api-reference/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](/pt-BR/api-reference/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. | A lista completa de eventos e os schemas de payload estão na [Referência de webhooks](/pt-BR/api-reference/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 | 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) | 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.