Subscription webhooks

Overview

Subscription webhooks provide real-time notifications about changes to subscriptions. This document outlines the different webhook events you may receive and provides details about the payload structure and handling of each event.

Webhook Events

1. Subscription Created

Event Type: customer.subscription.created

• Description: Triggered when a subscription is created but not yet started, meaning the very first payment has not been successfully deducted.

• Typical Scenario: A user signs up for a subscription plan, but their initial payment fails.

2. Subscription Started

Event Type: customer.subscription.started

• Description: Triggered when a subscription enters into active mode after the first successful payment.

• Typical Scenario: A user’s initial payment is successfully processed, and their subscription becomes active.

3. Subscription Unpaid

Event Type: customer.subscription.unpaid

• Description: Triggered when the system is unable to charge the user during renewal after multiple retries over a period of 7 days.

• Typical Scenario: A user's payment method fails, and all retry attempts to collect the subscription fee are exhausted.

4. Subscription Past Due

Event Type: customer.subscription.past_due

• Description: Triggered when the system is unable to charge the user during renewal on the first try, changing the subscription status from active to past_due. If the payment is successfully collected after a retry, the status changes back to active. If all retries fail over 7 days, the status changes from past_due to unpaid.

• Typical Scenario: A user's payment method fails on the first attempt, but a subsequent retry within 7 days may still succeed.

5. Subscription Canceled

Event Type: customer.subscription.deleted

• Description: Triggered when a subscription is canceled at the end of the current period.

• Typical Scenario: A user decides to cancel their subscription, and it is set to end at the current period's end.

Sample Webhook Payload

Below is an example payload for the customer.subscription.started event. The structure of the payload is consistent across different subscription events, with the type field indicating the specific event type.

{
  "id": "f5cd23ed-8e1a-44b6-9a36-5dadeebf1971",
  "apiVersion": "2023-01-11",
  "created": 1697724495349,
  "object": "subscription",
  // Type will be different based on different webhook types
  "type": "customer.subscription.started", 
  "data": {
    "object": {
      "collectionMethod": "charge_automatically",
      "paymentMethodTypes": [
        "allowance_based_recurring"
      ],
      "id": "ec75bcc9-afdc-4bc5-9cef-5f3fb073cdd0",
      "createdAt": "2023-10-19T14:07:47.149Z",
      "updatedAt": "2023-10-19T14:07:47.740Z",
      "organizationId": "820784c2-7ada-4c8a-adca-b37f0973c067",
      "clientReferenceId": null,
      "currency": "usdc",
      "interval": "month",
      "intervalCount": 1,
      "status": "active",
      "description": null,
      "metadata": {},
      "defaultPaymentMethodId": "b3530e00-1507-4b4d-94c8-45c1227ac8c5",
      "customerId": "293d8bc5-6ba7-4cb7-b99d-2041c7403b46",
      "startDate": "2023-10-19T14:07:47.149Z",
      "endedAt": null,
      "cancelAt": null,
      "canceledAt": null,
      "cancellationReason": null,
      "currentPeriodEnd": "2023-11-19T14:07:47.149Z",
      "currentPeriodStart": "2023-10-19T14:07:47.149Z",
      "cancelAtPeriodEnd": true
    }
  }
}

Handling Webhooks

When you receive a webhook event, the type field indicates the specific type of event. The data.object field contains the latest data about the subscription, including its status, payment method, and relevant timestamps.

Example Workflow for Handling a Subscription Event

1. Parse the Webhook Payload: Extract the event type and the subscription object.

2. Identify the Event Type: Use the type field to determine the specific subscription event.

3. Update Subscription Status: Update your records based on the latest status provided in the data.object.

4. Trigger Appropriate Actions: Depending on the event type, trigger the necessary actions, such as sending a notification to the user or updating user's account status on your application.

No-Code Solution with Zapier

If you prefer a no-code solution, you can use our Zapier application to configure automations or alerts for your team. Zapier allows you to connect Copperx with various other applications and automate workflows without writing any code.

Get started with the Copperx Zapier integration