API Tutorials
HELP CENTERINTEGRATIONSSTATUS PAGESIGN UP

Webhooks - In-App Purchase Topics

Suggest Edits

Cleeng Webhooks

Webhooks are notifications that Cleeng sends out to subscribed publishers about certain events occurring in the platform. The events are sent in the form of a POST request made to specified endpoints with a JSON payload as its body.

The body of the request consists of three constant fields:

broadcasterId – the ID of the publisher that the webhook is sent for,
topic – the name of the topic that the webhook is sent about,
data – topic-specific payload about the event.

Available In-App Purchase Topics

The following webhook topics are used for in-app purchases:

To find out more about validation of in-app purchases, visit Webhooks - In-App Purchase Validation section.

inappPurchaseSyncResult

Note: This webhook is currently available only for purchases made via Apple StoreKit 2 integrations

Trigger:

This webhook is triggered after a purchase synchronization or transfer process initiated by the Apple StoreKit 2 /purchases or /purchases/transfers endpoint is completed.

It provides the final status and result of the operation, including details about the transaction, access grant status, offer ID, and result code.

Important: This webhook is emitted only when the purchase processing status is finalized. You can use the /purchases/synchronizations/{synchronizationId} (Apple StoreKit 2) endpoint to track the status of the synchronization process.

Possible values of the result of the purchase processing:

  • RECEIVED_EXPIRED_PURCHASE: The purchase was already expired when received. This could be due to an old purchase being selected, an attempt to hack the system, or an application malfunction.
  • TRANSACTION_ID_NOT_FOUND: The transaction ID was not found in Apple's system. This could indicate an attempt to hack the system, a client app malfunction, or the purchase being cleared from the user's Apple account before it was registered.
  • ACCESS_EXPIRED: The purchase was successfully synchronized, but access to the offer has already expired. This could be due to a wrongly selected purchase or the user not extending access to the Apple offer.
  • OWNED_BY_ANOTHER_USER: The purchase is already owned by another user in the system. A transfer needs to be made to grant access to the requesting user.
  • SYNCHRONIZATION_UNPROCESSABLE: An unexpected system behavior prevented the synchronization process. This likely requires escalation to support.
  • RESOURCE_TEMPORARY_LOCKED_FOR_PROCESSING: The resource is temporarily locked due to a concurrent request. Retrying the request later should resolve the issue.
  • PRODUCT_TYPE_NOT_SUPPORTED: The product type is not supported by the system. Offers settings should be changed to make sure only supported products are available. Retrying the request doesn't make any positive effect before fixing offers configuration on Apple side and mappings in Cleeng's Dashboard.
  • PURCHASE_RESTORED: A purchase was found in the system that was not assigned to the end-user. Having data available from the request, the purchase was transferred from the system's unidentified user to the real user from the request. Real user have now granted access to the offer.
  • PURCHASE_OWNERSHIP_TRANSFERRED: The purchase was successfully transferred to another user. The new user now has access to the offer. The situation can occur only between real users.
  • PURCHASE_SYNCHRONIZED: The purchase was successfully synchronized.
{
  "synchronizationId": "a12345ab-1234-1ab1-1a12-1a1234ab123a",
  "correlationId": "string",
  "transaction": {
    "transactionId": "string",
    "cleengCustomerId": 0,
    "originalTransactionId": "string"
  },
  "accessGranted": true,
  "offerId": "string",
  "paymentMethodName": "string",
  "result": "RECEIVED_EXPIRED_PURCHASE"
}

inappPurchaseValidationSucceeded

Note: This webhook is deprecated for purchases made via Apple StoreKit 2 integrations.

Trigger:

The event is triggered when an in-app purchase validation is successful and ends with one of the success results: SubscriptionSynchronized, SubscriptionRevived, SubscriptionTransferred, SubscriptionCreated.

{
    "broadcasterId": 123456789, // same as  publisherId
    "topic": "inappPurchaseValidationSucceeded",
    "data": {
        "result": "SubscriptionSynchronized",
        "paymentGateway": "amazon",
        "offerId": "S123123123_US",
        "inAppSpecificData": {
            "receiptUserId": "receipt-user-id",
            "receiptId": "receipt-id"
        },
        "offerType": "subscription",
        "subscriptionId": 123456789,
        "active": true,
        "inTrial": false,
        "expirationDate": "2030-01-01T00:00:00+01:00",
        "customerId": 987654321
    }
}

Fields:

  • result - one of: SubscriptionSynchronized, SubscriptionRevived, SubscriptionTransferred, SubscriptionCreated
  • inAppSpecificData - it will differ depending on the gateway - for details see the In-App Specific Data section below
  • prevSubscriptionId - only present in case of subscription transfer
  • prevCustomerId - only present in case of subscription transfer
  • correlationId - only present when /purchase-validation endpoint requested

inappPurchaseValidationFailed

Note: This webhook is deprecated for purchases made via Apple StoreKit 2 integrations.

Trigger:
The event is triggered when an in-app purchase validation results in failure.

{
    "broadcasterId": 123456789, // same as  publisherId
    "topic": "inappPurchaseValidationFailed",
    "data": {
        "paymentGateway": "amazon",
        "offerId": "S123123123_US",
        "inAppSpecificData": {
            "receiptUserId": "receipt-user-id",
            "receiptId": "receipt-id"
        },
        "customerId": 987654321,
        "reason": "why it failed"
    }
}

In-App Specific Data

inAppSpecificData for each of the webhook topics above will differ depending on the gateway:

Apple iOS & tvOS

        "inAppSpecificData": {
            "originalTransactionId": "<originalTransactionId>",
            "transactionId": "<transactionId>"
        }

Android

        "inAppSpecificData": {
            "purchaseToken": "<purchaseToken>”
        }

Amazon FireTV

        "inAppSpecificData": {
            "receiptId": "<receiptId>",
            "receiptUserId": "<receiptUserId>"
        }

Samsung TV

        "inAppSpecificData": {
            "invoiceId": "<invoiceId>",
            "subscriptionId": "<subscriptionId>"
        }

Vizio

“InAppSpecificData”: {
  “invoiceNumber”: string,
  “subscriptionId”: string
}

Updated 5 days ago