Stripe

Timely.ai uses Stripe as its payment platform for plan charges, credits, and add-ons. When a relevant event occurs in your Stripe account (a subscription is created, an invoice is paid, a payment fails), Stripe sends a webhook to Timely’s servers, which updates the workspace status and may trigger internal events for your server. This page documents the Stripe events that Timely consumes, the payload formats, and how you can use this in your automations.

How Timely receives Stripe events

Stripe → POST to Timely.ai servers
         → Timely processes the event
         → Updates workspace status (credits, plan, billing)
         → Triggers internal webhook to your server (if configured)

You don’t need to configure anything in Stripe — Timely manages the webhook endpoint directly. What you can do is subscribe to Timely’s internal webhooks for billing events (such as credit.depleted or plan.changed) and react in your automations.

Consumed events

`checkout.session.completed`

Triggered when a customer successfully completes a checkout session. Timely uses this event to:

Activate the purchased plan in the workspace
Add acquired credits
Send a welcome or upgrade email

{
  "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"
    }
  }
}

The metadata.workspace_id field is inserted by Timely when creating the session to correlate the payment with the correct workspace.

`invoice.paid`

Triggered on every successfully paid invoice — both on the first charge and on monthly/annual renewals.

{
  "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
            }
          }
        ]
      }
    }
  }
}

Upon receiving invoice.paid, Timely renews the workspace’s access period and reloads the plan’s monthly credits.

`invoice.payment_failed`

Triggered when a charge attempt fails (card declined, insufficient funds, 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."
        }
      }
    }
  }
}

After a payment failure, Timely enters a grace period (typically 3 days) and sends notifications to the workspace owner.

`customer.subscription.updated`

Triggered on any subscription change: upgrade, downgrade, scheduled cancellation, billing period change.

{
  "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
    }
  }
}

The previous_attributes field contains only the fields that changed — use it to identify exactly what was modified.

`customer.subscription.deleted`

Triggered when the subscription is effectively terminated (not just scheduled — actually canceled).

{
  "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
    }
  }
}

Upon receiving this event, Timely moves the workspace to the free plan (if available) or suspends access.

Stripe events to Timely events mapping

Stripe event	Action in Timely	Timely internal webhook
`checkout.session.completed`	Activates plan, adds credits	`plan.changed`
`invoice.paid`	Renews period, reloads credits	—
`invoice.payment_failed`	Starts grace period	`credit.low` (if credits are low)
`customer.subscription.updated`	Updates plan limits	`plan.changed`
`customer.subscription.deleted`	Suspends or downgrades	`plan.changed`

Security and idempotency fields

All Stripe events include:

Field	Description
`id`	Unique event ID (`evt_*`) — use for deduplication
`created`	Creation Unix timestamp
`livemode`	`true` in production, `false` in test mode
`type`	Event type

In test environments, the livemode field is false. Timely processes Stripe test and production events separately. Never mix test and production API keys.

How Timely receives Stripe events

Consumed events

`checkout.session.completed`

`invoice.paid`

`invoice.payment_failed`

`customer.subscription.updated`

`customer.subscription.deleted`

Stripe events to Timely events mapping

Security and idempotency fields

Next steps

Billing events

Webhooks — API Reference

​How Timely receives Stripe events

​Consumed events

​checkout.session.completed

​invoice.paid

​invoice.payment_failed

​customer.subscription.updated

​customer.subscription.deleted

​Stripe events to Timely events mapping

​Security and idempotency fields

​Next steps

Billing events

Webhooks — API Reference

How Timely receives Stripe events

Consumed events

`checkout.session.completed`

`invoice.paid`

`invoice.payment_failed`

`customer.subscription.updated`

`customer.subscription.deleted`

Stripe events to Timely events mapping

Security and idempotency fields

Next steps