Subscription Status

Learn how to get subscription status changes to your server via webhooks

This webhook service keeps you informed about any changes related to subscriptions, such as new subscriptions, renewals, updates in grace status, or subscription cancellations.

Setup the Endpoint URL

Webhook events are sent to your server via HTTP POST. You configure the endpoint URL through Developer Tools / Webhooks menu under your project.

Webhook Events Sending Rules

The webhook notification for subscription status changes is sent within the first 5 minutes. For the delivery to be considered successful, your system must return an HTTP 200 status code. Any status code other than 200 will be considered a failure, and the following retry process will apply:

• If the delivery fails, the process will be retried after 10 minutes.

• If the second attempt fails, the next three attempts will be made at 30-minute intervals.

• If the delivery still fails after these three attempts, the next retry will occur 1 hour later.

• If this attempt also fails, the process will not be retried, and the process will be terminated.

Events Format

Webhook events are serialized in JSON. The body of a POST request to your server will contain the serialized event.

{
  "queue": {
    "type": "SubscriberUpdate",
    "eventType": "newSubscriber",
    "requestID": "5a33b022-b877-4888-9eed-89a294640a3c",
    "createDate": {
      "date": "2024-05-13 08:18:22.978000",
      "timezone_type": 3,
      "timezone": "UTC"
    },
    "appId": 1651
  },
  "parameters": {
    "profile": {
      "status": "active",
      "realStatus": "active",
      "subscriberId": "[e-mail]",
      "subscriptionId": 10414,
      "subscriptionType": "trial",
      "startDate": "2024-05-13 08:18:22",
      "expireDate": "2024-05-16 08:18:22",
      "renewalDate": "2024-05-16 08:18:22",
      "package": "paypal_test",
      "country": "TR",
      "phoneNumber": null,
      "language": "en",
      "originalTransactionId": "bfe87fcd-72f7-4902-88ba-b2695c829590",
      "lastTransactionId": "bfe87fcd-72f7-4902-88ba-b2695c829590",
      "subscriptionPackageType": "single",
      "cancellation": null,
      "customParameters": {
        "clientUuid": "5adf7031-34f3-402b-88fc-2fe8cc87d0af",
        "dataWarehouse": {
          "paymentModule": "generate",
          "siteId": 1088,
          "flowId": 2879,
          "appId": 1094,
          "teamId": 189,
          "acceptPolicy": true
        },
        "utm": {
          "source": null,
          "medium": null,
          "campaign": null,
          "term": null,
          "content": null
        }
      },
      "quantity": 1,
      "pendingQuantity": 0,
      "renewalFetchCount": 0
    },
    "package": {
      "packageId": "paypal_test",
      "price": 1,
      "currency": "TRY",
      "packageType": "subscription",
      "name": "paypal_test",
      "subscriptionPackageType": "single",
      "bundlePackages": []
    },
    "newPackage": null,
    "card": {
      "cardNumber": "41111111****1111",
      "expireDate": "06/2024",
      "tokenId": 11082
    },
    "customer": null,
    "package_update": 0
  }
}

Fields

queue	It contains information on the webhook type and history.
queue.type	It specifies the transaction type. For this webhook type, SubscriberUpdate always comes.
queue.eventType	It specifies updates related to the subscription. It can take the following values: newSubscriber: Indicates that there is a new subscriber. Cancel: Indicates that the subscription has been canceled. reactivate: Indicates that the subscription has been reactivated. activeToGrace: Indicates that an active subscriber has transitioned to a 'grace' status. graceToActive: Indicates that a subscriber in 'grace' status has transitioned to active status. graceToPassive: Indicates that a subscriber in 'grace' status has transitioned to passive status. renewal: Indicates that the subscription has been renewed."
parameters	Contains the details on Webhook info.
package	Includes information on the subscriber's active or most recently used package.
newPackage	This field contains the package information to be sent if the subscriber has downgraded their package. It is returned as null if there is no package change.
customer	This is the parameter through which the subscriber's Zotlo information is sent.
card	It's the service that sends registered credit card information.
profile	This is the service that sends the subscriber's subscription status, such as the expiration date. The subscriber's status can be determined by looking at the status value.
profile.customParameters	This parameter is used to send relevant records to the subscriber if specific parameters are supplied to the subscriber during the subscription. Null is the default value
profile.quantity	The number of people who have access to a subscription is returned here if it has been opened to more than one user. The default values is 1.
profile.cancellation	If the subscription is canceled, this parameter contains the reason for the cancellation as well as the cancellation date. The subscription is sent as null if it is not canceled. This parameter should be used to check the subscriber's cancellation status
profile.originalTransactionId	This is the transactionId value of the subscriber's first purchase.
profile.subscriptionType	It can take paid or trial values. If it's a trial, the subscriber is still in the trial period, and if it's a paid subscription, at least one payment has been received
profile.subscriberId	This is the subscriber's unique ID value sent by the client at the start of the subscription. This subscriberId is used to make all system queries.
profile.expireDate	The subscription's expiration date.
profile.package	This is the subscriber's current active package ID.
profile.status	The subscriber's current status. It can be set to active, passive, or grace parameters. The subscription will continue if it is active. The subscription is terminated if it is passive. If the subscription parameter is grace, it means that the subscription could not be renewed because it could not be charged. The status value for users who cancel their subscription appears as active until the expireDate arrives
profile.realStatus	The subscriber's actual status. Unlike the active parameter, it returns the subscriber's current status. Even if the subscription does not expire, users who cancel it are treated as passive in this parameter.
profile.country	The subscriber's country code.
profile.phoneNumber	This is the phone number of the subscriber that is on file in the system.
package_update	The value 1 is used if the notification is sent after the package change. In all other cases, the value 0 is sent.