Set up upload callbacks for mobile apps

Prerequisites

Before you begin, ensure that you have:

• Completed Set up direct data transfer for mobile applications — your Android or iOS app must already upload directly to OSS using Security Token Service (STS) tokens

• An app server with a public IP address that can receive POST requests

• A publicly accessible callback URL (for example, http://example.com/callback.php)

Use cases

Upload callbacks are useful when your server needs to act on uploads as they happen:

• User-generated content tracking: Record which user uploaded a profile photo, document, or video, along with the file's name, size, and MIME type.

• Device metadata collection: Capture the app version, OS version, GPS coordinates, or device model alongside each upload — without requiring a separate API call from the client.

• Post-upload processing: Trigger downstream workflows (database updates, image processing, notifications) the moment an upload lands in OSS.

How it works

The flow involves three parties: the mobile app, OSS, and your app server.

1. Steps 1–4 (not shown in detail): The mobile app authenticates with your app server and gets an STS token.

2. Step 5: The Android or iOS app sends an upload request to OSS. The request includes callbackUrl and callbackBody, which tell OSS where to send the callback and what data to include.

3. Step 6: After receiving the object, OSS sends a POST callback request to your app server at the callbackUrl.

4. Step 7: Your app server processes the request and returns a JSON response. OSS forwards that response to the mobile app as the upload result.

For full callback specification details, see Callback.

System variables

When OSS sends the callback request to your app server, the callbackBody can include any combination of the following system variables. You specify which variables to include when configuring the upload request on the mobile app.

Configure upload callbacks on the mobile app

To trigger a callback, include callbackUrl and callbackBody in every upload request. You can also pass custom variables — prefixed with x: — to send client-side metadata to your server.

Parameters to include in each upload request:

Custom variable naming: Custom variables must start with x: (for example, x:phone, x:system, x:gps, x:version). OSS passes these through to your server in the callbackBody.

OSSPutObjectRequest *request = [OSSPutObjectRequest new];
request.bucketName = @"<bucketName>";
request.objectKey  = @"<objectKey>";
request.uploadingFileURL = [NSURL fileURLWithPath:@"<filepath>"];

// Set the callback URL and the fields to send to your server.
request.callbackParam = @{
    @"callbackUrl":  @"http://example.com/callback.php",
    @"callbackBody": @"filename=${object}&size=${size}&phone=${x:phone}&system=${x:system}"
};

// Set custom variable values.
request.callbackVar = @{
    @"x:phone":  @"iphone6s",
    @"x:system": @"ios9.1"
};

PutObjectRequest put = new PutObjectRequest(testBucket, testObject, uploadFilePath);

ObjectMetadata metadata = new ObjectMetadata();
metadata.setContentType("application/octet-stream");
put.setMetadata(metadata);

// Set the callback URL and the fields to send to your server.
put.setCallbackParam(new HashMap<String, String>() {{
    put("callbackUrl",  "http://example.com/callback.php");
    put("callbackBody", "filename=${object}&size=${size}&phone=${x:phone}&system=${x:system}");
}});

// Set custom variable values.
put.setCallbackVars(new HashMap<String, String>() {{
    put("x:phone",  "iPhone 6s");
    put("x:system", "YunOS5.0");
}});

App server requirements

Your app server must:

• Accept POST requests at the callbackUrl endpoint.

• Have a public IP address so OSS can reach it. Example: http://example.com/callback.php.

• Return a JSON response. OSS forwards this response directly to the mobile app as the upload result. You can include any fields in the JSON body.

Verify that the callback is from OSS

If your server is internet-facing, it may receive requests from sources other than OSS. To confirm that a callback is genuine, perform RSA signature verification on the x-oss-pub-key-url and authorization headers in the incoming POST request. Only requests that pass RSA signature verification originate from OSS.

The sample programs in the next section include this RSA verification logic — use them as a reference.

Example callback request your server receives (based on the iOS and Android configuration above):

POST /index.html HTTP/1.0
Host: 203.0.113.0
Connection: close
Content-Length: 81
Content-Type: application/x-www-form-urlencoded
User-Agent: ehttp-client/0.0.1
authorization: kKQe**************/kdD1ktNVgbWE**************
x-oss-pub-key-url: aHR0**************

filename=test.txt&size=5&phone=iphone6s&system=ios9.1

After your server verifies the signature and parses the body, it can store the extracted data (filename, size, phone model, OS version) for ongoing management.

How OSS handles server responses

Download sample programs

The following sample programs implement RSA signature verification for the callback server. Each program validates the incoming callback's signature but does not parse the callbackBody — add that parsing logic based on the fields you configured in callbackBody.

• Java

  • Download: AppCallbackServer.zip

  • Run: java -jar oss-callback-server-demo.jar 9000 (9000 is the default port; you can change the port number as needed)

  • > Note: The JAR requires OSS SDK for Java 1.7. If errors occur, refer to the included Maven project source and modify as needed.

• PHP

  • Download: callback-php-demo.zip

  • Run: Deploy to an Apache environment. An Apache environment is required to obtain certain headers due to PHP-specific features — modify the sample code based on your actual environment.

• Python

  • Download: callback_app_server.py.zip

  • Run: python callback_app_server.py — this starts a minimal HTTP server. Install RSA dependencies if prompted.

• Ruby

  • Download: oss-callback-server (GitHub)

  • Run: ruby server.rb

FAQ