Logs
Histórico técnico por pagamento e assinatura. Onde aparece, o que contém, retenção e sanitização.
A Allya Payments grava um histórico técnico de cada operação relevante: criação de pagamento/assinatura, chamada ao gateway, recebimento de webhook inbound, envio de webhook outbound, erros de validação e de transporte.
Logs ficam disponíveis somente no painel (não há rota pública para consulta). Eles são uma ferramenta de operação e auditoria, não de telemetria em tempo real.
Onde aparece
- Detalhe do pagamento (
/projects/[id]/payments/[paymentId]): linha do tempo do pagamento, com cada interação registrada. - Detalhe da assinatura (
/projects/[id]/subscriptions/[subscriptionId]): ciclo de vida da assinatura e cobranças vinculadas. - Logs do projeto (
/projects/[id]/logs): visão consolidada por ambiente, com filtros por tipo, status e período.
Tipos de log (kind)
| Kind | Quando aparece |
|---|---|
API_REQUEST | Chamada recebida pela API pública da Allya, como criação, sync ou cancelamento. |
GATEWAY_REQUEST | Requisição HTTP feita pela Allya para o gateway. |
GATEWAY_RESPONSE | Resposta recebida do gateway após uma chamada bem-sucedida. |
GATEWAY_ERROR | Chamada ao gateway terminou em erro HTTP, timeout ou falha de rede. |
WEBHOOK_RECEIVED | Webhook inbound recebido do gateway (assinatura válida). |
WEBHOOK_SENT | Webhook outbound enviado para um endpoint do cliente. |
WEBHOOK_FAILED | Tentativa de envio outbound falhou ou webhook inbound foi ignorado por motivo registrável. |
PAYMENT_STATUS_CHANGED | Status normalizado de um pagamento mudou. |
SUBSCRIPTION_STATUS_CHANGED | Status normalizado de uma assinatura mudou. |
Campos comuns
Cada entrada de log carrega ao menos:
- timestamp: momento da operação (ISO).
- kind: tipo do evento (tabela acima).
- organization / project / environment: escopo do log (denormalizado para limpeza por retenção).
- payment / subscription: vínculo opcional com o recurso afetado.
- status code: código HTTP da chamada (em
GATEWAY_RESPONSE,GATEWAY_ERROR,WEBHOOK_SENTeWEBHOOK_FAILED, quando disponível). - request / response sanitizados: corpo da chamada com dados sensíveis mascarados (ver abaixo).
- error message: quando aplicável, mensagem curta do erro.
O que é sanitizado
A Allya nunca persiste em log:
- Header
Authorization(substituído porBearer ***). - Header
access_token,asaas-access-token,X-Webhook-Signature,x-hub-signature(mascarados). webhookSecret, API keys completas, secret keys de gateway.customer.documentcompleto (apenas os últimos 4 dígitos do CPF/CNPJ aparecem; o restante é hashado em outro local).- Dados de cartão: número, CVV, validade, titular: esses nunca chegam à Allya porque a Allya usa checkout hospedado do gateway, então também nunca podem aparecer em log.
metadataé mantido como veio do cliente, exceto quando algum campo bater com a lista de chaves sensíveis acima.
Antes de enviar PII ou segredos em metadata, considere se aquilo precisa mesmo ir junto: o log mantém o metadata para investigação.
Retenção por plano
Logs são limpos automaticamente pelo job cleanup conforme a janela do plano:
| Plano | Retenção |
|---|---|
| Starter | 7 dias |
| Pro | 30 dias |
| Business | 90 dias |
| Custom | Definido no plano contratado |
A janela conta a partir do createdAt do log. Eventos mais antigos são deletados em background: não há recuperação após o expurgo.
Job de cleanup
O job lê todos os logs com idade maior que a retenção contratada e remove em lote. Em produção, a Allya agenda o cleanup diariamente.
Limitações
- Sem rota pública: logs não saem por API.
- Sem exportação CSV/JSON no painel: feature ainda no roadmap.
- Sem filtro full-text dentro do payload sanitizado: busca atual é por kind, status code e janela de tempo.
- Sem alertas baseados em log: sem integração com PagerDuty / Slack ainda.
Para correlação rápida durante um incidente, use gatewayRef ou externalId no painel de pagamentos/assinaturas: eles abrem direto o detalhe com a timeline.
Veja também
- Webhooks: webhooks falhos aparecem como
WEBHOOK_FAILEDno log do pagamento associado. - Troubleshooting: passos para investigar pagamentos parados, com referência aos logs como primeira ferramenta.