A Timely.ai usa o Stripe como plataforma de pagamentos para cobranças de plano, créditos e add-ons. Quando um evento relevante acontece na sua conta Stripe (uma assinatura é criada, uma fatura é paga, um pagamento falha), o Stripe envia um webhook para os servidores da Timely, que atualiza o status do workspace e pode disparar eventos internos para o seu servidor.
Esta página documenta os eventos Stripe que a Timely consome, o formato dos payloads e como você pode usar isso nas suas automações.
Como a Timely recebe eventos do Stripe Stripe → POST para servidores Timely.ai → Timely processa o evento → Atualiza status do workspace (créditos, plano, billing) → Dispara webhook interno para seu servidor (se configurado)
Você não precisa configurar nada no Stripe — a Timely gerencia o endpoint de webhook diretamente. O que você pode fazer é assinar os webhooks internos da Timely para eventos de billing (como credit.depleted ou plan.changed) e reagir nas suas automações.
Eventos consumidos checkout.session.completedDisparado quando um cliente finaliza uma sessão de checkout com sucesso. A Timely usa esse evento para:
Ativar o plano comprado no workspace
Adicionar créditos adquiridos
Enviar email de boas-vindas ou upgrade
{ "id" : "evt_1NabcXYZ" , "object" : "event" , "type" : "checkout.session.completed" , "created" : 1713456789 , "data" : { "object" : { "id" : "cs_test_a1b2c3d4e5" , "object" : "checkout.session" , "mode" : "subscription" , "payment_status" : "paid" , "status" : "complete" , "customer" : "cus_ABC123" , "subscription" : "sub_DEF456" , "metadata" : { "workspace_id" : "uuid-do-workspace" , "plan" : "pro" , "credits" : "5000" }, "amount_total" : 19700 , "currency" : "brl" } } }
O campo metadata.workspace_id é inserido pela Timely na criação da sessão para correlacionar o pagamento com o workspace correto.
invoice.paidDisparado em toda fatura paga com sucesso — tanto na primeira cobrança quanto nas renovações mensais/anuais.
{ "id" : "evt_1NabcXYZ2" , "object" : "event" , "type" : "invoice.paid" , "created" : 1713543200 , "data" : { "object" : { "id" : "in_1NabcXYZ2" , "object" : "invoice" , "customer" : "cus_ABC123" , "subscription" : "sub_DEF456" , "status" : "paid" , "amount_paid" : 19700 , "currency" : "brl" , "period_start" : 1713456789 , "period_end" : 1716048789 , "lines" : { "data" : [ { "description" : "Timely Pro — Maio 2026" , "amount" : 19700 , "period" : { "start" : 1713456789 , "end" : 1716048789 } } ] } } } }
Ao receber invoice.paid, a Timely renova o período de acesso do workspace e recarrega os créditos mensais do plano.
invoice.payment_failedDisparado quando uma tentativa de cobrança falha (cartão recusado, saldo insuficiente, etc.).
{ "id" : "evt_1NabcXYZ3" , "object" : "event" , "type" : "invoice.payment_failed" , "created" : 1713543400 , "data" : { "object" : { "id" : "in_1NabcXYZ3" , "object" : "invoice" , "customer" : "cus_ABC123" , "subscription" : "sub_DEF456" , "status" : "open" , "attempt_count" : 2 , "next_payment_attempt" : 1713629800 , "last_finalization_error" : null , "payment_intent" : { "last_payment_error" : { "code" : "card_declined" , "decline_code" : "insufficient_funds" , "message" : "Your card has insufficient funds." } } } } }
Após falha de pagamento, a Timely entra em período de graça (geralmente 3 dias) e envia notificações para o owner do workspace.
customer.subscription.updatedDisparado em qualquer mudança na assinatura: upgrade, downgrade, cancelamento agendado, mudança de período de cobrança.
{ "id" : "evt_1NabcXYZ4" , "object" : "event" , "type" : "customer.subscription.updated" , "created" : 1713543600 , "data" : { "object" : { "id" : "sub_DEF456" , "object" : "subscription" , "customer" : "cus_ABC123" , "status" : "active" , "cancel_at_period_end" : true , "current_period_start" : 1713456789 , "current_period_end" : 1716048789 , "items" : { "data" : [ { "price" : { "id" : "price_1NabcXYZ5" , "nickname" : "Timely Pro Mensal" , "unit_amount" : 19700 , "currency" : "brl" , "recurring" : { "interval" : "month" } } } ] } }, "previous_attributes" : { "cancel_at_period_end" : false } } }
O campo previous_attributes contém apenas os campos que mudaram — use-o para identificar exatamente o que foi alterado.
customer.subscription.deletedDisparado quando a assinatura é efetivamente encerrada (não agendada — efetivamente cancelada).
{ "id" : "evt_1NabcXYZ6" , "object" : "event" , "type" : "customer.subscription.deleted" , "created" : 1716048800 , "data" : { "object" : { "id" : "sub_DEF456" , "object" : "subscription" , "customer" : "cus_ABC123" , "status" : "canceled" , "ended_at" : 1716048789 } } }
Ao receber esse evento, a Timely move o workspace para o plano gratuito (se disponível) ou suspende o acesso.
Mapeamento de eventos Stripe para eventos Timely Evento Stripe Ação na Timely Webhook interno Timely checkout.session.completedAtiva plano, adiciona créditos plan.changedinvoice.paidRenova período, recarrega créditos — invoice.payment_failedInicia período de graça credit.low (se créditos baixos)customer.subscription.updatedAtualiza limites do plano plan.changedcustomer.subscription.deletedSuspende ou downgrade plan.changed
Campos de segurança e idempotência Todos os eventos Stripe incluem:
Campo Descrição idID único do evento (evt_*) — use para deduplicação createdUnix timestamp de criação livemodetrue em produção, false em modo testetypeTipo do evento
Em ambientes de teste, o campo livemode é false. A Timely processa separadamente eventos de teste e produção do Stripe. Nunca misture as API keys de teste e produção.
Próximos passos
Eventos de billing Webhooks internos da Timely para eventos de crédito e plano.
Webhooks — API Reference Configure endpoints para receber eventos do seu workspace.
