Skip to main content

Subscription webhooks

OrcaRail sends webhook events for subscription lifecycle and billing. Use the same webhook endpoint and signature verification as for Payment Intents; subscription events use the same payload shape: type and data.object.

Event types​

EventDescription
subscription.createdSubscription was created
subscription.updatedSubscription was updated
subscription.canceledSubscription was canceled (immediate or at period end)
subscription.pausedSubscription was paused
subscription.resumedSubscription was resumed from paused
subscription.trial_will_endTrial ends in 3 days (reminder)
subscription.payment_link.createdA cycle payment link was created
subscription.payment_link.paidCycle payment confirmed (link paid or auto-charge succeeded)
subscription.payment_link.payment_failedAuto-charge pull failed for this cycle
subscription.past_dueSubscription moved to past_due (overdue or failed payment)
subscription.completedAll cycles completed (total_cycles reached)

Payload structure​

All subscription events follow the same structure:

{
  "type": "subscription.payment_link.paid",
  "data": {
    "object": {
      "id": "sub_550e8400e29b41d4a716446655440000",
      "object": "subscription",
      "status": "active",
      "collection_method": "send_payment_link",
      "amount": "10.00",
      "currency": "usd",
      "description": "Monthly Pro Plan",
      "interval": "month",
      "interval_count": 1,
      "total_cycles": 12,
      "completed_cycles": 3,
      "current_period_start": "2025-03-01T00:00:00Z",
      "current_period_end": "2025-04-01T00:00:00Z",
      "payer": { "id": "...", "email": "[email protected]" },
      "latest_payment_link": {
        "id": "...",
        "status": "completed",
        "link": "..."
      },
      "metadata": {},
      "created": "2025-01-01T00:00:00Z",
      "updated": "2025-03-15T00:00:00Z"
    }
  }
}

data.object is the full subscription object (see Overview). For subscription.payment_link.paid or subscription.payment_link.created, you can use data.object.latest_payment_link for the current cycle's link.

Example handler​

const subscriptionHandlers = {
  'subscription.created': (event) => {
    console.log('New subscription:', event.data.object.id)
  },
  'subscription.updated': (event) => {
    console.log('Subscription updated:', event.data.object.id)
  },
  'subscription.canceled': (event) => {
    const sub = event.data.object
    console.log('Canceled:', sub.id, sub.canceled_at)
  },
  'subscription.payment_link.paid': (event) => {
    const sub = event.data.object
    // Fulfill access for this cycle, extend license, etc.
    console.log('Cycle paid:', sub.id, 'cycle', sub.completed_cycles)
  },
  'subscription.payment_link.payment_failed': (event) => {
    const sub = event.data.object
    // Notify payer, retry logic, or downgrade
    console.log('Auto-charge failed:', sub.id)
  },
  'subscription.past_due': (event) => {
    console.log('Past due:', event.data.object.id)
  },
  'subscription.completed': (event) => {
    console.log('All cycles done:', event.data.object.id)
  },
  'subscription.trial_will_end': (event) => {
    const sub = event.data.object
    console.log('Trial ending soon:', sub.id, sub.trial_end)
  },
}

// In your webhook route:
if (event.type.startsWith('subscription.')) {
  const handler = subscriptionHandlers[event.type]
  if (handler) await handler(event)
}

Idempotency​

As with all webhooks, events may be delivered more than once. Use event.type + event.data.object.id (and optionally the cycle or link id) to deduplicate and process each event only once.

Next steps​