Skip to main content

Server Webhook

note

Webhooks are a feature of paid plans.

Definition

Upon receiving a receipt request in the Receipt Validator, we can forward the App Store response to your server endpoint for further processing. This allows implementing custom behaviour on your backend for potentially backing up user inventory or getting more insights into user workflows using advanced purchase statistics. This is a paid-plan feature.

Webhook010

You can enter your server endpoint in the app settings, by navigating to Apps > App Options > Edit. When saving a webhook address for the first time, your endpoint must respond with a 200 status code to prove its existence. Also, a new header private key will be generated.

note

Please be informed that only valid purchase receipts are sent to your server. A valid receipt is defined as a successful purchase that increased your validation count, i.e. a new purchase or subscription renewal. Additionally in case of subscriptions, subscription status changes (i.e. paused, expired) are forwarded as well.

Two different types of webhooks can be used. The Simple webhook type is included in all paid plans by default.

Webhook TypeDescription
SimpleIn case of system outages or failures on the receiving server, there is no retry or queue mechanism and the webhook message sent is lost. This type can be used for analytical purposes but should not be used to replicate user inventory.
ReliableIn case of a failed response on the receiving server, the webhook message is retried every 5 minutes up to a maximum of 30 minutes (6 times) after the original message was sent. This type can be used to replicate user inventory.
note

Reliable webhooks can be requested on a CUSTOM plan.

FieldValue
Content-Typeapplication/json
X-App-IdYour 16 alphanumeric characters long app identifier.
X-Auth-KeyAuto-generated private key. Check this in your backend to ensure the request source is actually valid. Contact Support if your key was compromised.

Content

A string in JSON format.

FieldValue
storeThe originating App Store. GooglePlay or AppleAppStore
userOnly present on user-initiated receipt requests, like a purchase or restore. App Store server-server notifications do not provide user identifiers.

The client-provided or server generated (v4 UUID) unique user identifier.
transactionApp Store-generated unique transaction identifier.
data
(object)
Receipt data of the purchase. For more information please refer to the validation response.
timestampUNIX timestamp when the request was created. If you are using Reliable Webhooks, check this field to determine whether the message is still valid in case it has been sent with a retry delay.

Example

/*
PHP Example for processing webhook data on your server
*/

//Read App ID from Request and compare
$appId = $_SERVER['HTTP_X_APP_ID'];
if($appId === null || $appId !== '<YOUR-APP-ID>')
{
exit;
}

//Read API Key from Request and compare
$appKey = $_SERVER['HTTP_X_AUTH_KEY'];
if($appKey === null || $appKey !== '<YOUR-API-KEY>')
{
exit;
}

//Receive content from incoming POST request
$body = json_decode(file_get_contents('php://input'), true);
//Read User ID from parsed content
$user = $body->user;
//Read Product ID from parsed content
$product = $body->data->productId;

//Your implementation
//e.g. connect to local database and award product to user
$this->grantToUser($user, $product)